Merge pull request #135 from prometheus/http-api-docs

Document HTTP API v1.

content/docs/querying/api.md

+---
+title: HTTP API
+sort_rank: 7
+---
+
+# HTTP API
+
+The current stable HTTP API is reachable under `/api/v1` on a Prometheus
+server. Any non-breaking additions will be added under that endpoint.
+
+## Format overview
+
+The API response format is JSON. Every successful API request returns a `2xx`
+status code.
+
+Invalid requests that reach the API handlers return a JSON error object
+and the HTTP response code `422 Unprocessable Entity`
+([RFC4918](http://tools.ietf.org/html/rfc4918#page-78)). Other non-`2xx` codes
+may be returned for errors occurring before the API endpoint is reached.
+
+The JSON response envelope format is as follows:
+
+```
+{
+  "status": "success" | "error",
+  "data": <data>,
+
+  // Only set if status is "error". The data field may still hold
+  // additional data.
+  "errorType": "<string>",
+  "error": "<string>"
+}
+```
+
+Input timestamps may be provided either in
+[RFC3339](https://www.ietf.org/rfc/rfc3339.txt) format or as a Unix timestamp
+in seconds, with optional decimal places for sub-second precision. Output
+timestamps are always represented as Unix timestamps in seconds.
+
+Names of query parameters that may be repeated end with `[]`.
+
+`<series_selector>` placeholders refer to Prometheus [time series
+selectors](/docs/querying/basics/#time-series-selectors) like
+`http_requests_total` or `http_requests_total{method=~"^GET|POST$"}` and need
+to be URL-encoded.
+
+`<duration>` placeholders refer to Prometheus duration strings of the form
+`[0-9]+[smhdwy]`. For example, `5m` refers to a duration of 5 minutes.
+
+## Expression queries
+
+Query language expressions may be evaluated at a single instant or over a range
+of time. The sections below describe the API endpoints for each type of
+expression query.
+
+### Instant queries
+
+The following endpoint evaluates an instant query at a single point in time:
+
+```
+GET /api/v1/query
+```
+
+URL query parameters:
+
+- `query=<string>`: Prometheus expression query string.
+- `time=<rfc3339 | unix_timestamp>`: Evaluation timestamp.
+
+The `data` section of the query result has the following format:
+
+```
+{
+  "resultType": "matrix" | "vector" | "scalar" | "string",
+  "result": <value>
+}
+```
+
+`<value>` refers to the query result data, which has varying formats
+depending on the `resultType`. See the [expression query result
+formats](#expression-query-result-formats).
+
+The following example evaluates the expression `up` at the time
+`2015-07-01T20:10:51.781Z`:
+
+```
+$ curl 'http://localhost:9090/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'
+{
+   "status" : "success",
+   "data" : {
+      "resultType" : "vector",
+      "result" : [
+         {
+            "metric" : {
+               "__name__" : "up",
+               "job" : "prometheus",
+               "instance" : "localhost:9090"
+            },
+            "value": [ 1435781451.781, "1" ]
+         },
+         {
+            "metric" : {
+               "__name__" : "up",
+               "job" : "node",
+               "instance" : "localhost:9100"
+            },
+            "value" : [ 1435781451.781, "0" ]
+         }
+      ]
+   }
+}
+```
+
+### Range queries
+
+The following endpoint evaluates an expression query over a range of time:
+
+```
+GET /api/v1/query_range
+```
+
+URL query parameters:
+
+- `query=<string>`: Prometheus expression query string.
+- `start=<rfc3339 | unix_timestamp>`: Start timestamp.
+- `end=<rfc3339 | unix_timestamp>`: End timestamp.
+- `step=<duration>`: Query resolution step width.
+
+The `data` section of the query result has the following format:
+
+```
+{
+  "resultType": "matrix",
+  "result": <value>
+}
+```
+
+For the format of the `<value>` placeholder, see the [range-vector result
+format](#range-vectors).
+
+The following example evaluates the expression `up` over a 30-second range with
+a query resolution of 15 seconds.
+
+```
+$ curl 'http://localhost:9090/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'
+{
+   "status" : "success",
+   "data" : {
+      "resultType" : "matrix",
+      "result" : [
+         {
+            "metric" : {
+               "__name__" : "up",
+               "job" : "prometheus",
+               "instance" : "localhost:9090"
+            },
+            "values" : [
+               [ 1435781430.781, "1" ],
+               [ 1435781445.781, "1" ],
+               [ 1435781460.781, "1" ]
+            ]
+         },
+         {
+            "metric" : {
+               "__name__" : "up",
+               "job" : "node",
+               "instance" : "localhost:9091"
+            },
+            "values" : [
+               [ 1435781430.781, "0" ],
+               [ 1435781445.781, "0" ],
+               [ 1435781460.781, "1" ]
+            ]
+         }
+      ]
+   }
+}
+```
+
+## Querying metadata
+
+### Finding series by label matchers
+
+The following endpoint returns the list of time series that match a certain label set.
+
+```
+GET /api/v1/series
+```
+
+URL query parameters:
+
+- `match[]=<series_selector>`: Repeated series selector argument that selects the
+  series to return. At least one `match[]` argument must be provided.
+
+The `data` section of the query result consists of a list of objects that
+contain the label name/value pairs which identify each series.
+
+The following example returns all series that match either of the selectors
+`up` or `process_start_time_seconds{job="prometheus"}`:
+
+```
+$ curl -g 'http://localhost:9090/api/v1/series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'
+{
+   "status" : "success",
+   "data" : [
+      {
+         "__name__" : "up",
+         "job" : "prometheus",
+         "instance" : "localhost:9090"
+      },
+      {
+         "__name__" : "up",
+         "job" : "node",
+         "instance" : "localhost:9091"
+      },
+      {
+         "__name__" : "process_start_time_seconds",
+         "job" : "prometheus",
+         "instance" : "localhost:9090"
+      }
+   ]
+}
+```
+
+### Querying label values
+
+The following endpoint returns a list of label values for a provided label name:
+
+```
+GET /api/v1/label/<label_name>/values
+```
+
+The `data` section of the JSON response is a list of string label names.
+
+This example queries for all label values for the `job` label:
+
+```
+$ curl http://localhost:9090/api/v1/label/job/values
+{
+   "status" : "success",
+   "data" : [
+      "node",
+      "prometheus"
+   ]
+}
+```
+
+## Deleting series
+
+The following endpoint deletes matched series entirely from a Prometheus server:
+
+```
+DELETE /api/v1/series
+```
+
+URL query parameters:
+
+- `match[]=<series_selector>`: Repeated label matcher argument that selects the
+  series to delete. At least one `match[]` argument must be provided.
+
+The `data` section of the JSON response has the following format:
+
+```
+{
+  "numDeleted": <number of deleted series>
+}
+```
+
+The following example deletes all series that match either of the selectors
+`up` or `process_start_time_seconds{job="prometheus"}`:
+
+```
+$ curl -XDELETE -g 'http://localhost:9090/api/v1/series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'
+{
+   "status" : "success",
+   "data" : {
+      "numDeleted" : 3
+   }
+}
+```
+
+## Expression query result formats
+
+Expression queries may return the following response values in the `result`
+property of the `data` section. `<sample_value>` placeholders are numeric
+sample values. JSON does not support special float values such as `NaN`, `Inf`,
+and `-Inf`, so sample values are transferred as quoted JSON strings rather than
+raw numbers.
+
+### Range vectors
+Range vectors are returned as result type `matrix`. The corresponding
+`result` property has the following format:
+
+```
+[
+  {
+    "metric": { "<label_name>": "<label_value>", ... },
+    "values": [ [ <unix_time>, "<sample_value>" ], ... ]
+  },
+  ...
+]
+```
+
+### Instant vectors
+Instant vectors are returned as result type `vector`. The corresponding
+`result` property has the following format:
+
+```
+[
+  {
+    "metric": { "<label_name>": "<label_value>", ... },
+    "value": [ <unix_time>, "<sample_value>" ]
+  },
+  ...
+]
+```
+
+### Scalars
+Scalar results are returned as result type `scalar`. The corresponding
+`result` property has the following format:
+
+```
+[ <unix_time>, "<scalar_value>" ]
+```
+
+### Strings
+String results are returned as result type `string`. The corresponding
+`result` property has the following format:
+
+```
+[ <unix_time>, "<string_value>" ]
+```

content/docs/querying/basics.md

@@ -9,7 +9,7 @@ sort_rank: 1
 Prometheus provides a functional expression language that lets the user select
 and aggregate time series data in real time. The result of an expression can
 either be shown as a graph, viewed as tabular data in Prometheus's expression
-browser, or consumed by external systems via the HTTP API.
+browser, or consumed by external systems via the [HTTP API](/docs/querying/api/).
 
 ## Examples
 

content/docs/querying/index.md

 ---
-title: Query language
+title: Querying
 sort_rank: 3
 nav_icon: search
 ---