Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
..
Failed to load latest commit information.
alerts
ext
messages
properties
series
README.md
aggregation.md
date-format.md
error-codes.md
filter-date.md
filter-entity.md
reference.md
severity.md

README.md

Overview

The Data API lets you insert and retrieve series, properties, messages, and alerts from the Axibase Time Series Database.

Categories

Request Methods

The API uses the POST method to read, write, and delete data except for series url and property url queries.

Request Headers

When submitting payload with the POST method in JSON format, add the header Content-Type: application/json.

For correct Unicode handling, specify the charset Content-Type: application/json;chartset=UTF-8.

URI Encoding

Request parameter values and parameterized path segments, such as /api/v1/properties/{entity}/types, should be URL encoded to translate special characters, such as : / ? # [ ] @, into a percent format that can be transmitted safely as part of the request URI.

Input Encoded Value URI
station/24 station%2F24 /api/v1/properties/station%2F24/types

Failure to encode URI components may result in 4xx and 5xx errors:

Status Code: 500
{"error":"...HttpRequestMethodNotSupportedException: Request method 'GET' not supported"}

Date/Time Formats

Supported date input formats:

  • yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'
  • yyyy-MM-dd'T'HH:mm:ss[.SSS]±hh:mm

Refer to ISO 8601 date format examples.

  • Minimum time that can be stored in the database is 1970-01-01T00:00:00.000Z, or 0 millisecond from Epoch time.
  • Maximum date that can be stored by the database is 2106-02-07T06:59:59.999Z, or 4294969199999 milliseconds from Epoch time.
  • Maximum date that can be specified in ISO format when querying data is 9999-12-31T23:59:59.999 UTC.

Number Formatting

  • Decimal separator is a period (.).
  • No thousands separator.
  • No digit grouping.
  • Negative numbers use a negative sign (-) at the beginning of the number.
  • Not-a-Number is literal NaN unless specified otherwise.

Syntax

  • Entity name, metric name, property type, and key/tag names must consist of printable characters.
  • Field names are case-insensitive and are converted to lower case when stored in the database.
  • Field values are case-sensitive and are stored as submitted, except for entity name, metric name, and property type, which are converted to lower case.
  • Values are trimmed of starting and trailing line breaks (CR,LF symbols).

Wildcards

* and ? wildcards are supported in entity name and tag value.

The literal symbols ? and * should be escaped with a single backslash.

Response Codes

  • 200 status code if the request is successful.
  • 401 status code in case of an unknown resource.
  • 403 status code in case of access denied error.
  • 4xx status code in case of other client errors.
  • 5xx status code in case of server error.

4xx or 5xx response codes are specific to each API method.

Errors

Processing errors are returned in JSON format:

{"error":"Empty first row"}

Authentication

  • User authentication is required.
  • All requests must be authenticated using BASIC AUTHENTICATION.
  • The authentication method is HTTP BASIC.
  • The client may use session cookies to execute multiple requests without repeating authentication.

Authorization

Cross-Domain Requests

Cross-domain requests are allowed.

Compression

  • Clients may send compressed data by adding HTTP header Content-Encoding: gzip to the request.

Troubleshooting

  • Review error logs on Admin:Server Logs page in case the payload is rejected.
  • To validate JSON received from a client, launch the netcat utility in server mode, reconfigure the client to send data to netcat port, and dump the incoming data to file:
nc -lk 0.0.0.0 20088 > json-in.log &

curl http://localhost:20088/api/v1/series/insert \
  -v -u {username}:{password} \
  -H "Content-Type: application/json" \
  -X POST \
  -d '[{"entity": "nurswgvml007", "metric": "mpstat.cpu_busy", "data": [{ "t": 1462427358127, "v": 22.0 }]}]'

cat json-in.log

Examples

Each Data API method provides a set of examples containing sample request and response objects.

The response object illustrates all fields returned by the method.

Basic Java Examples: