HTTP API

OpenTSDB 提供一个基于 HTTP 的API以与外部系统集成. 几乎所有的 OpenTSDB 特征都,像查询时间序列数据,管理元数据,存储数据点都通过API操作.在研究单个节点之前,请阅读本业关于标准API操作的重要信息.

概述

HTTP API本质上是REST式的，但通过各种重写提供了替代访问，因为并非所有客户机都能遵守严格的REST协议.虽然可能会通过可卸载formatters插件,通过请求,来收发不同格式化的数据, 但默认数据交换是通过JSON .所有返回的结果和错误都会使用适当的内容返回标准HTTP响应码.

Version 1.X to 2.x

OpenTSDB 1.x 有个简单的 HTTP API 为常见行为提供访问,比如查询数据,自动完成查询,还有静态文件请求.OpenTSDB 2.0用文档介绍了一个新的, 形式化的API. 1.0 API虽然大多数过已经过时,但仍然可以访问,并且或许在版本3会被移除. 所有2.0 API 起始于/api/.

Serializers

2.0引入可插入的序列化器，允许解析用户输入，并以不同格式返回结果，如XML或JSON. 序列化器只适用于2.0 API调用，所有1.0的行为都与以前一样。 关于序列化器的细节和选项支持,请阅读HTTP Serializers

所有 API默认使用JSON格式,除非用查询语句或Content-Type头重写 . 重写:

• Query String- 为输出字段显示在/api/serializers serializer 的<serializer_name>是序列化器名称硬编码提供像serializer=<serializer_name>的参数.

  警告

  如果序列化器没有找到匹配<serializer_name>的值,查询会返回一个错误而不是进一步处理.

• Content-Type- 如果没有给定查询语句, TSD会在Content-Type头解析HTTP请求. Each serializer may supply a content type and if matched to the incoming request, the proper serializer will be used. If a serializer isn't located that maps to the content type, the default serializer will be used.

• Default- If no query string parameter is given or the content-type is missing or not matched, the default JSON serializer will be used.

The API documentation will display requests and responses using the JSON serializer. See plugin documentation for the ways in which serializers alter behavior.

Note

The JSON specification states that fields can appear in any order, so do not assume the ordering in given examples will be preserved. Arrays may be sorted and if so, this will be documented.

认证/权限

As of yet, OpenTSDB lacks an authentication and access control system. Therefore no authentication is required when accessing the API. If you wish to limit access to OpenTSDB, use network ACLs or firewalls to block access. We do not recommend running OpenTSDB on a machine with a public IP Address.

响应码

Every request will be returned with a standard HTTP response code. Most responses will include content, particularly error codes that will include details in the body about what went wrong. Successful codes returned from the API include:

Common error response codes include:

错误

If an error occurs, the API will return a response with an error object formatted per the requested response type. Error object fields include:

All errors will return with a valid HTTP status error code and a content body with error details. The default formatter returns error messages as JSON with theapplication/jsoncontent-type. If a different formatter was requested, the output may be different. See the formatter documentation for details.

Example Error Result

{
    "error": {
        "code": 400,
        "message": "Missing parameter <code>type</code>",
        "trace": "net.opentsdb.tsd.BadRequestException: Missing parameter <code>type</code>\r\n\tat net.opentsdb.tsd.BadRequestException.missingParameter(BadRequestException.java:78) ~[bin/:na]\r\n\tat net.opentsdb.tsd.HttpQuery.getRequiredQueryStringParam(HttpQuery.java:250) ~[bin/:na]\r\n\tat net.opentsdb.tsd.SuggestRpc.execute(SuggestRpc.java:63) ~[bin/:na]\r\n\tat net.opentsdb.tsd.RpcHandler.handleHttpQuery(RpcHandler.java:172) [bin/:na]\r\n\tat net.opentsdb.tsd.RpcHandler.messageReceived(RpcHandler.java:120) [bin/:na]\r\n\tat org.jboss.netty.channel.SimpleChannelUpstreamHandler.handleUpstream(SimpleChannelUpstreamHandler.java:75) [netty-3.5.9.Final.jar:na]\r\n\tat org.jboss.netty.channel.DefaultChannelPipeline.sendUpstream(DefaultChannelPipeline.java:565) [netty-3.5.9.Final.jar:na]
        ....\r\n\tat java.lang.Thread.run(Unknown Source) [na:1.6.0_26]\r\n"
    }
}

Note that the stack trace is truncated. Also, the trace will include system specific line endings (in this case\r\nfor Windows). If displaying for a user or writing to a log, be sure to replace the\nor\r\nand\rcharacters with new lines and tabs.

Verbs

The HTTP API is RESTful in nature, meaning it does it's best to adhere to the REST protocol by using HTTP verbs to determine a course of action. For example, aGETrequest should only return data, aPUTorPOSTshould modify data andDELETEshould remove it. Documentation will reflect what verbs can be used on an endpoint and what they do.

However in some situations, verbs such asDELETEandPUTare blocked by firewalls, proxies or not implemented in clients. Furthermore, most developers are used to usingGETandPOSTexclusively. Therefore, while the OpenTSDB API supports extended verbs, most requests can be performed with justGETby adding the query string parametermethod_override. This parameter allows clients to pass data for most API calls as query string values instead of body content. For example, you can delete an annotation by issuing aGETwith a query string/api/annotation?start_time=1369141261&tsuid=010101&method_override=delete. The following table describes verb behavior and overrides.

If a method is not supported for a given API call, the TSD will return a 405 error.

Note

The HTTP specification states that there shouldn't be an association between data passed in a request body and the URI in aGETrequest. Thus OpenTSDB's API does not parse body content inGETrequests. You can, however, provide a query string with data and an override for updating data in certain endpoints. But we recommend that you usePOSTfor anything that writes data.

API Versioning

OpenTSDB 2.0's API call calls are versioned so that users can upgrade with gauranteed backwards compatability. To access a specific API version, you craft a URL such as/api/v<version>/<endpoint>such as/api/v2/suggest. This will access version 2 of thesuggestendpoint. Versioning starts at 1 for OpenTSDB 2.0.0. Requests for a version that does not exist will result in calls to the latest version. Also, if you do not supply an explicit version, such as/api/suggest, the latest version will be used.

Query String Vs. Body Content

Most of the API endpoints support query string parameters, particularly those that fetch data from the system. However due to the complexities of encoding some characters, and particularly Unicode, all endpoints also support access via POST content using formatters. The default format is JSON so clients can use their favorite means of generating a JSON object and send it to the OpenTSDB API via aPOSTrequest.POSTrequests will generally provided greater flexibility in the fields offered and fully Unicode support than query strings.

Compressed Requests

The API can accept body content that has been compressed. Make sure to set theContent-Encodingheader togzipand pass the binary encoded data over the wire. This is particularly useful for posting data points to the/api/putendpoint. An example using curl:

$ gzip -9c clear-32k.json > gzip-32k.json

$ file gzip-32k.json
gzip-32k.json: gzip compressed data, was "clear-32k.json", from Unix, last modified: Thu Jan 16 15:31:55 2014

$ ls -l gzip-32k.json
-rw-r--r-- 1 root root 1666 févr.  4 09:57 gzip-32k.json

$ curl -X POST --data-binary "@gzip-32k.json" --header "Content-Type: application/json" --header "Content-Encoding: gzip" http://mytsdb1:4242/api/put?details
{"errors":[],"failed":0,"success":280}

CORS

OpenTSDB provides simple and preflight support for Cross-Origin Resource Sharing (CORS) requests. To enable CORS, you must supply either a wild card*or a comma separated list of specific domains in thetsd.http.request.cors_domainsconfiguration setting and restart OpenTSDB. For example, you can supply a value of*or you could provide a list of domains such asbeeblebrox.com,www.beeblebrox.com,aurtherdent.com. The domain list is case insensitive but must fully match any value sent by clients.

When aGET,POST,PUTorDELETErequest arrives with theOriginheader set to a valid domain name, the server will compare the domain against the configured list. If the domain appears in the list or the wild card was set, the server will add theAccess-Control-Allow-OriginandAccess-Control-Allow-Methodsheaders to the response after processing is complete. The allowed methods will always beGET,POST,PUT,DELETE. It does not change per end point. If the request is a CORS preflight, i.e. theOPTIONmethod is used, the response will be the same but with an empty content body and a 200 status code.

If theOrigindomain did not match a domain in the configured list, the response will be a 200 status code and an Error (see above) for the content body stating that access was denied, regardless of whether the request was a preflight or a regular request. The request will not be processed any further.

By default, thetsd.http.request.cors_domainslist is empty and CORS is diabled. Requests are passed through without appending CORS specific headers. If anOptionsrequest arrives, it will receive a 405 error message.

Note

Do not rely on CORS for security. It is exceedingly easy to spoof a domain in an HTTP request and OpenTSDB does not perform reverse lookups or domain validation. CORS is only implemented as a means to make it easier JavaScript developers to work with the API.

Documentation

The documentation for each endpoint listed below will contain details about how to use that endpoint. Eahc page will contain a description of the endpoint, what verbs are supported, the fields in a request, fields in a respone and examples.

Request Parameters are a list of field names that you can pass in with your request. Each table has the following information:

• Name - The name of the field
• Data Type - The type of data you need to supply. E.g. String should be text, Integer must be a whole number (positive or negative), Float should be a decimal number. The data type may also be a complex object such as an array or map of values or objects. If you see Present in this column then simply adding the parameter to the query string sets the value to true , the actual value of the parameter is ignored. For example /api/put?summary will effectively set summary=true . If you request /api/put?summary=false , the API will still consider the request as summary=true .
• Required - Whether or not the parameter is required for a successful query. If the parameter is required, you'll see Required otherwise it will be Optional .
• Description - A detailed description of the parameter including what values are allowed if applicable.
• Default - The default value of the Optional parameter. If the data is required, this field will be blank.
• QS - If the parameter can be supplied via query string, this field will have a Yes in it, otherwise it will have a No meaning the parameter can only be supplied as part of the request body content.
• RW - Describes whether or not this parameter can result in an update to data stored in OpenTSDB. Possible values in this column are:
  • empty
    • This means that the field is for queries only and does not, necessarily, represent a field in the response.
  • RO
    • A field that appears in the response but is read only. The value passed along with a request will not alter the output field.
  • RW or W
    • A field that will result in an update to the data stored in the system
• Example - An example of the parameter value

Deprecated API

ReadDeprecated HTTP API

API Endpoints

• /s
• /api/aggregators
• /api/annotation
• /api/config
• /api/dropcaches
• /api/put
• /api/rollup
• /api/histogram
• /api/query
• /api/search
• /api/serializers
• /api/stats
• /api/suggest
• /api/tree
• /api/uid
• /api/version