1. Response status code
  2. Update POST request
    1. Headers
    2. Body
  3. Successful response
  4. Example
  5. Example using curl

Ingress

Data is ingested into Warp 10™ via HTTP POST requests to the update endpoint.

The update endpoint is https://HOST:PORT/api/v0/update, where HOST:PORT is a valid endpoint for the Warp 10™ instance and vX is the version of the API you want to use.

The Ingress API must be accessed using the POST method.

All requests MUST be authenticated, as described below.

Response status code

HTTP status codes are used to indicate the request action that happened during the process (success, redirection, client error, server error). The following status are common:

CodeDescription
200Successful request. All datapoints pushed were stored successfully.
500Error: details in response body. Errors can occur due to syntax or quota issues.

Update POST request

POST /api/v0/update

Headers

To be authenticated you need to add an X-Warp10-Token header with a valid WRITE token.

HeaderDescription
X-Warp10-TokenA valid WRITE token

Body

The body of the POST request contains the Geo Time Series™ data in GTS input format, one reading by line.

The general format is:

TS/LAT:LON/ELEV NAME{LABELS} VALUE

please refer to the detailed documentation of the input format for a more throughout tour of the GTS input format.

GTS Input Format:

ParameterDescription
TSTimestamp of the reading, in the configured time units since the Unix Epoch.
If omitted, the time of the data ingestion will be used as the time of each reading
LAT:LONOptional geographic coordinates of the reading, using WGS84
ELEVOptional elevation of the reading, in millimeters
NAMEClass name of the reading as a URL encoded UTF-8 character string.
The encoding of character { (Unicode LEFT CURLY BRACKET, 0x007B) is MANDATORY.
LABELSComma separated list of labels, using the syntax key=value where both key and value are URL encoded UTF-8 character strings.
If a key or value contains , (Unicode COMMA, 0x002C), } (Unicode RIGHT CURLY BRACKET, 0x007D) or = (Unicode EQUALS SIGN, 0x003D), those characters MUST be encoded.
VALUEThe value of the reading. It can be of one of four types: LONG, DOUBLE, BOOLEAN, STRING
  • Numerical values are considered LONG if they do not contain a decimal point or if they are expressed in scientific notation.
  • BOOLEAN values can be expressed as true, false, T or F.
  • STRING values must be percent-encoded, in UTF-8 and enclosed in matching simple or double quotes.

Successful response

Upon receiving a successful response from the endpoint (HTTP 200), the data has been stored to disk (in the case of the Standalone version), in memory (if the Standalone was configured with an in-memory storage backend) or pushed to Kafka (in the case of the Distributed version).

Example

POST /api/v0/update HTTP/1.1
Host: host
X-Warp10-Token: TOKEN
Content-Type: text/plain

1380475081000000// foo{label0=val0,label1=val1} 123
/48.0:-4.5/ bar{label0=val0} 3.14
1380475081123456/45.0:-0.01/10000000 foobar{label1=val1} T

Example using curl

curl -H 'X-Warp10-Token: TOKEN_WRITE' -H 'Transfer-Encoding: chunked' -T METRICS_FILE 'https://HOST:PORT/api/v0/update'

Where TOKEN_WRITE is a valid write token for the platform, METRICS_FILE is text file where every line is a GTS input format and API_ENDPOINT is a valid endpoint for the public Warp 10™ API.

The Transfer-Encoding header is needed, otherwise curl will try to materialize the data in memory which will lead to failures when you attempt to push millions or billions of datapoints at once.

Here you have sample METRICS_FILE:

1382441207762000/51.501988:0.005953/ some.sensor.model.humidity{xbeeId=XBee_40670F0D,moteId=53,area=1} 79.16
1382441237727000/51.501988:0.005953/ some.sensor.model.humidity{xbeeId=XBee_40670F0D,moteId=53,area=1} 75.87
1382441267504000/51.501988:0.005953/ some.sensor.model.humidity{xbeeId=XBee_40670F0D,moteId=53,area=1} 74.46
1382441267504000/51.501988:0.005953/ some.sensor.model.humidity{xbeeId=XBee_40670F0D,moteId=53,area=1} 73.55
1382441297664000/51.501988:0.005953/ some.sensor.model.humidity{xbeeId=XBee_40670F0D,moteId=53,area=1} 72.30
1382441327765000/51.501988:0.005953/ some.sensor.model.humidity{xbeeId=XBee_40670F0D,moteId=53,area=1} 70.73
1382441327765000/51.501988:0.005953/ some.sensor.model.humidity{xbeeId=XBee_40670F0D,moteId=53,area=1} 69.50
1382441357724000/51.501988:0.005953/ some.sensor.model.humidity{xbeeId=XBee_40670F0D,moteId=53,area=1} 68.24
1382441387792000/51.501988:0.005953/ some.sensor.model.humidity{xbeeId=XBee_40670F0D,moteId=53,area=1} 66.66
1382441387792000/51.501988:0.005953/ some.sensor.model.humidity{xbeeId=XBee_40670F0D,moteId=53,area=1} 65.73