Axibase Time Series Database

REST API

The REST API allows you to insert and retrieve data from the database using HTTP requests.

Requests

Request Methods

To read data from the database, use GET and POST methods.

To write data into the database, use POST, PUT, PATCH, and DELETE methods.

API Content Path

The API context path is /api/v1/ and must include the current v1 API version.

Sample API endpoints:

/api/v1/series/query
/api/v1/series/insert
/api/v1/series/delete

Request Headers

When submitting a payload in JSON format, add the Content-Type: application/json;charset=UTF-8 header.

URI Encoding

Request parameters and path segments, such as /api/v1/properties/{entity}/types, must 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
jvm/memory(max) jvm%2Fmemory%28max%29 /api/v1/metrics/jvm%2Fmemory%28max%29
station/24 station%2F24 /api/v1/properties/station%2F24/types

Failure to properly encode URI components results in HTTP 4xx and 5xx errors.

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

Compression

Clients can send compressed payload by adding the Content-Encoding: gzip header to the request.

Security

Authentication

  • User authentication is required.
  • All requests must be authenticated using BASIC AUTHENTICATION.
  • Session cookies can be used to execute subsequent requests without re-sending BASIC authentication header

Authorization

Data API Authorization

Meta API Authorization

Cross-Domain Requests

Cross-domain requests are allowed.

Schema and Syntax

Dates

Supported date input patterns:

Pattern Example
yyyy-MM-ddTHH:mm:ss[.S]Z Z denotes UTC time zone.
2018-05-15T00:00:00Z
2018-05-15T00:00:00.002Z
yyyy-MM-ddTHH:mm:ss[.S]±hh[:]mm Offset from UTC time zone in hours and minutes.
2018-05-15T00:00:00-05:00
2018-05-15T00:00:00-0500

Refer to Date Format specification and examples.

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

Numbers

  • The decimal separator is a period (.).
  • No thousands separator is allowed.
  • No digit grouping is allowed.
  • Negative numbers must begin with a negative sign (-).
  • Not-a-Number is the literal string NaN unless specified otherwise.

Strings

  • Entity name, metric name, property type, and key/tag names must consist of printable characters.
  • Field names are case-insensitive and are converted to lowercase 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 lowercase.
  • Values are stripped of starting and trailing line breaks (CR,LF symbols).

Wildcards

Wildcard characters asterisk (*) and question mark (?) are supported in entity name and tag value filters.

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

Limits

The number of tags in the inserted record cannot exceed the following limit:

Command Maximum Tags
series 1024 series tags
property 1024 keys and tags
message 1024 message tags

Responses

HTTP Status Codes

  • 200 OK or 204 No Content status code if the request is successful.
  • 401 Unauthorized status code on unknown resource.
  • 403 Forbidden status code on access denied error.
  • 4xx status code on other client errors.
  • 5xx status code on server error.

Errors

Processing errors are returned in JSON format:

{"error":"Empty first row"}

Authentication and authorization error codes are listed in the Administration guide.

Troubleshooting

  • Review error logs on the Settings > Diagnostics > Server Logs page if the payload is rejected.
  • To eliminate authentication issues, submit the request using the built-in API client on the Data > API Client page.
  • To validate JSON received from a client, launch the netcat utility in server mode, reconfigure the client to send data to the netcat port, and dump the incoming data to file:
nc -lk -p 20088 > json-in.log &

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

cat json-in.log

Each API method below provides examples containing sample request and response objects.

Data API Endpoints

The endpoints listed below are accessible under the /api/v1/ context path, for example /api/v1/series/insert, except SQL.

Series

Name Method / Path / Description
get GET /series/{format}/{entity}/{metric}
Retrieves series values for the specified entity, metric, and series tags in CSV and JSON format.
query POST /series/query
Retrieves series values for the specified filters in JSON format. Supports advanced filtering and transformation options compare to get method.
insert POST /series/insert
Inserts a timestamped array of numbers for a given series identified by metric, entity, and series tags.
insert CSV POST /series/csv/{entity}
Inserts series values for the specified entity and series tags in CSV format.
delete POST /series/delete
Deletes series for the specified entity, metric, and optional series tags.

Messages

Name Method / Path / Description
insert POST /messages/insert
Inserts an array of messages.
webhook POST or GET /messages/webhook/*
Creates message from an HTTP request with optional JSON payload and insert it.
query POST /messages/query
Retrieves message records for the specified filters.
delete - - -
Deletes message records.
stats POST /messages/stats/query
Calculates the number and maximum severity of messages per period.

Properties

Name Method / Path / Description
get GET /properties/{entity}/types/{type}
Retrieves property records for the specified entity and type.
query POST /properties/query
Retrieves property records matching specified filters.
get types GET /properties/{entity}/types
Retrieves an array of property types for the entity.
insert POST /properties/insert
Inserts an array of properties.
delete POST /properties/delete
Deletes property records that match specified filters.

Alerts

Name Method / Path / Description
query POST /alerts/query
Retrieves open alerts for specified filters.
history query POST /alerts/history/query
Retrieves closed alerts for specified filters.
update POST /alerts/update
Changes acknowledgement status of the specified open alerts.
delete POST /alerts/delete
Deletes specified alerts by id from the memory store.

SQL

Name Method / Path / Description
SQL query POST /api/sql
Executes an SQL query and retrieves results in CSV or JSON format.
SQL meta query POST /api/sql/meta
Retrieves SQL query result metadata in JSON format without executing the query.

Extended

Name Method / Path / Description
command POST /command
Inserts data using commands in Network API via HTTP.
upload CSV POST /csv
Accepts CSV file or multiple CSV files for parsing into series, properties, or messages with the specified CSV parser.
upload nmon POST /nmon
Accepts nmon file for parsing.

Meta API Endpoints

The endpoints are accessed under context path /api/v1/, for example /api/v1/version.

Metric

Name Method / Path / Description
get GET /metrics/{metric}
Retrieves properties and tags for the specified metric.
list GET /metrics
Retrieves a list of metrics matching the specified filter conditions.
update PATCH /metrics/{metric}
Updates fields and tags of the specified metric.
create or replace PUT /metrics/{metric}
Creates a metric with specified fields and tags or replaces the fields and tags of an existing metric.
delete DELETE /metrics/{metric}
Deletes the specified metric.
series GET /metrics/{metric}/series
Returns a list of series for the metric.
series tags GET /metrics/{metric}/series/tags
Returns a list of unique series tag values for the metric.

Entity

Name Method / Path / Description
get GET /entities/{entity}
Retrieves information about the specified entity including its tags.
list GET /entities
Retrieves a list of entities matching the specified filter conditions.
update PATCH /entities/{entity}
Updates fields and tags of the specified entity.
create or replace PUT entities/{entity}
Creates an entity with specified fields and tags or replaces the fields and tags of an existing entity.
delete DELETE /entities/{entity}
Deletes the specified entity and delete it as member from any entity groups that it belongs to.
entity groups GET /entities/{entity}/groups
Retrieves a list of entity groups to which the specified entity belongs.
metrics GET /entities/{entity}/metrics
Retrieves a list of metrics collected by the entity.
property types GET /entities/{entity}/property-types
Retrieves a list property types for the entity.

Entity Group

Name Method / Path / Description
get GET /entity-groups/{group}
Retrieves information about the specified entity group including its tags.
list GET /entity-groups
Retrieves a list of entity groups.
update PATCH /entity-groups/{group}
Updates fields and tags of the specified entity group.
create or replace PUT /entity-groups/{group}
Creates an entity group with specified fields and tags or replaces the fields and tags of an existing entity group.
delete DELETE /entity-groups/{group}
Deletes the specified entity group.
get entities GET /entity-groups/{group}/entities
Retrieves a list of entities that are members of the specified entity group and are matching the specified filter conditions.
add entities POST /entity-groups/{group}/entities/add
Adds entities as members to the specified entity group.
set entities POST /entity-groups/{group}/entities/set
Sets members of the entity group from the specified entity list.
delete entities POST /entity-groups/{group}/entities/delete
Removes specified entities from members of the specified entity group.

Replacement Tables

Name Method / Path / Description
get CSV GET /replacement-tables/csv/{name}
Retrieves replacement table keys and values in CSV format and metadata in Link header.
get JSON GET /replacement-tables/json/{name}
Retrieves replacement table keys, values, and metadata in JSON format.
list CSV GET /replacement-tables/csv
Retrieves list of replacement table names in CSV format.
list JSON GET /replacement-tables/json
Retrieves list of replacement table names in JSON format.
update CSV PATCH /replacement-tables/csv/{name}
Updates values for existing keys or create new records from CSV file.
update JSON PATCH /replacement-tables/json/{name}
Updates replacement table and metadata from JSON document.
create or replace CSV PUT /replacement-tables/csv/{name}
Creates a replacement table with specified records or replace if exists.
create or replace JSON PUT /replacement-tables/json/{name}
Creates a replacement table with specified records and metadata, or replace if table already exists.
delete DELETE /replacement-tables/{name}
Deletes specified replacement table.

Miscellaneous

Name Method / Path / Description
version GET /version
Returns database version including licensing details as well as a date object with local time and offset.
ping GET /ping
Returns HTTP 200 OK status code to check connectivity and authentication.
permissions GET /permissions
Returns roles and permissions for the current user.
series search GET /search
Search series by an expression.
portal export GET /portal/export
Export portal screenshot as PNG file.

get →