Documentation improvement.

docs/API.md

@@ -0,0 +1,95 @@
+# Metricator's API
+
+This page describes Metricator's API.
+
+## URL forming
+
+API URLs are formed like: `/api/vX/TYPE/OTHER_DATA`, where:
+
+* `vX` is a version (e.g. `v1`).
+* `TYPE` - request type (see below).
+* `OTHER_DATA` - other data that is needed to properly process request of `TYPE`.
+
+## Versions
+
+Metricator's API currently supports API version 1.
+
+## Handlers
+
+### Get Metricator's build info
+
+**URL**: `/api/vX/info`
+
+Returns a JSON with build info with following items:
+
+* `Branch` for git branch.
+* `Build` for commit **number**.
+* `CommitHash` for git commit hash.
+* `Version` for tagged (or not tagged) build.
+
+Caveats:
+
+1. `Version` contains string formed with [Semantic Versioning](https://semver.org/spec/v2.0.0.html) in mind, so there is either "X.Y.Z" for tagged release or "X.Y.Z-dev` for development (built not from tag) release.
+
+Example:
+
+```json
+{"Branch":"master","Build":"24","CommitHash":"095e24a2b0b908d790153a4ed0bee51d9dba7685","Version":"0.1.0-dev"}
+```
+
+### Get registered applications list
+
+**URL**: `/api/vX/apps_list`
+
+Returns a JSON with all known applications.
+
+Example:
+
+```json
+["app1", "app2", "gw1", "gw2"]
+```
+
+### Get all known metrics for application
+
+**URL**: `/api/vX/metrics/APP_NAME`
+
+Where:
+
+* `APP_NAME` is a name of registered application.
+
+Example:
+
+```json
+[
+    {
+        "Name":"dnsdist_frontend_tcpgaveup/frontend:127.0.0.1:53/proto:TCP/thread:0",
+        "Description":"Amount of TCP connections terminated after too many attempts to get a connection to the backend",
+        "Type":"counter",
+        "Value":"0",
+        "Params":null
+    },
+    {
+        "Name":"dnsdist_frontend_queries/frontend:127.0.0.1:53/proto:UDP/thread:0",
+        "Description":"Amount of queries received by this frontend",
+        "Type":"counter",
+        "Value":"0",
+        "Params":null
+    },
+    {
+        "Name":"dnsdist_frontend_queries/frontend:127.0.0.1:53/proto:UDP/thread:0",
+        "Description":"Amount of queries received by this frontend",
+        "Type":"counter",
+        "Value":"53842",
+        "Params":null,
+    }
+]
+```
+
+### Get single metric data
+
+**URL**: `/api/vX/metrics/APP_NAME/METRIC_NAME`
+
+Where:
+
+* `APP_NAME`  is a name of registered application.
+* `METRIC_NAME` is a name of metric exposed by this application.

docs/CONFIGURE.md

@@ -10,9 +10,13 @@ This page describes every configuration value.
 | applications > APPNAME > headers > MAP | map | Headers which should be added to request. See example below. |
 | applications > APPNAME > time_between_requests | string | time.Duration-compatible string which represents timeout between requests. |
 
+Where:
+
+* `APPNAME` is a custom name for application.
+
 ## Headers map example
 
-```
+```yaml
 applications:
   example:
     headers:

docs/INDEX.md

@@ -16,13 +16,13 @@ Metricator instead acts like Prometheus itself from monitored software PoV: it p
 
 Also Metricator "reformats" metric names and parameters to be more easily parsed if needed, so:
 
-```
+```prometheus
 dnsdist_frontend_responses{frontend="127.0.0.1:53",proto="UDP",thread="0"}
 ```
 
 became:
 
-```
+```prometheus
 dnsdist_frontend_responses/frontend:127.0.0.1:53/proto:UDP/thread:0
 ```
 
@@ -30,3 +30,4 @@ dnsdist_frontend_responses/frontend:127.0.0.1:53/proto:UDP/thread:0
 
 * [Installation](INSTALL.md)
 * [Configuration](CONFIGURE.md)
+* [API](API.md)

docs/INSTALL.md

@@ -12,7 +12,7 @@ This page describes all of them.
 
 To run Metricator in Docker simply run:
 
-```
+```bash
 docker run -v $(pwd)/metricator.yaml:/config.yaml -p 8080:34421 registry.gitlab.pztrn.name/pztrn/metricator:latest
 ```
 
@@ -20,7 +20,7 @@ Don't forget to create configuration file as described [here](CONFIGURE.md)!
 
 ### docker-compose
 
-```
+```docker-compose
 version: "2.4"
 
 services: