From cdfa948b7d806999db0273861782f09197ac003d Mon Sep 17 00:00:00 2001
From: "Stanislav N. aka pztrn" <pztrn@pztrn.name>
Date: Wed, 23 Dec 2020 21:33:39 +0500
Subject: [PATCH] Documentation improvement.

---
 docs/API.md       | 95 +++++++++++++++++++++++++++++++++++++++++++++++
 docs/CONFIGURE.md |  6 ++-
 docs/INDEX.md     |  5 ++-
 docs/INSTALL.md   |  4 +-
 4 files changed, 105 insertions(+), 5 deletions(-)
 create mode 100644 docs/API.md

diff --git a/docs/API.md b/docs/API.md
new file mode 100644
index 0000000..a03bf12
--- /dev/null
+++ b/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.
diff --git a/docs/CONFIGURE.md b/docs/CONFIGURE.md
index 0024f12..0f4a530 100644
--- a/docs/CONFIGURE.md
+++ b/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:
diff --git a/docs/INDEX.md b/docs/INDEX.md
index e67dc97..cb42c58 100644
--- a/docs/INDEX.md
+++ b/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)
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index d435636..53d9aca 100644
--- a/docs/INSTALL.md
+++ b/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: