Data collection via REST API

After connecting and authenticating your OAuth2 client to the REST API, your client can send https/http2 requests with data.

Route

For each device you created for each of its channels with data type FLOAT you can send time series to the Cloud. Given that you obtained an access token you may use the following route.

POST https://{hostname}/api/v2/in/ts/device/{device_identifier}

The {hostname} is part of the endpoint provided to you in response to your request by email mentioned in this article.

The {device_identifier} can either be the string representation of the device UUID, or the external ID of the device. If your devices or gateways cannot be configured in such a way that they would actually know their device UUID in graphicx, please use the external ID of your choice, which is an optional attribute of the device in graphicx.io. Make sure to your external ID is designed in such a way that it can be used in an URL path, possibly by applying URL-encoding.

Request Headers

The route requires three request headers to be present, which are described in the table below.

Request headerExample valueRequired or optionalDescription
AuthorizationBearer {access_token}requiredThis header is required as specified by the Internet standard OAuth2 as part of requests that an OAuth2 client sends to resource servers. {access_token} stands for the unaltered OAuth2 access token, just as your client obtained it.
X-ComzipoptionalID of the compression algorithm applied to the serialized data. One of lzma, lz4, snappy, bzip2, gzip, zip. If you choose not to apply any compression, please just do not send this header at all.
X-Fmt16requiredformat_id of the applied payload format.

Request Body

The request body must contain the data formatted and serialized with the payload format you announce in the request header X-Fmt, and optionally compressed with the compression algorithm you optionally announce in the request header X-Com. The available payload formats are documented in all detail in the articles protobuf payload formats and JSON payload formats.

Note: In case you are using constraint devices or gateways that do not have the capability to securely apply TLS (Transport Layer Security) and thus https/http2, do not hesitate to contact us. We do support the notion of VPN-protected non-TLS http endpoints for data collection.

Response Status Codes

The following table documents https/http2 response status codes with respect to this route and provides advice how to handle each case.

CodeDescription and advice
200OK. The data has been successfully parsed and has been persisted in the first stage of the data collection pipeline of the platform. Under normal operating circumstances, it will take only under a second until that data is written to the target data store, e.g. the main time series database of the platform. + However, under irregular operating circumstances, that can take longer. Don't worry, the data is buffered in the platform. Note that data from before January 2010 is considered too old and will automatically be discarded.
400Bad Request. Something more general is wrong with the request. Check for valid OAuth2 token in Authorization request header.
401Unauthorized. Check for valid OAuth2 token in Authorization request header. Your token may have expired. Consider obtaining a new token.
403Forbidden. Your client may have provided insufficient authorization. Also check the identifiers, or in other words, the coordinates of your data, e.g. a device identifier.
422Unprocessable Entity. This is a validation or parsing error. It indicates invalid or malformed request body content. Check compression, Content-Type, content format and actual, possibly compressed, content for validity and consistency.
500Internal Server Error. We are sorry about this. Please retry the request at a somewhat later point in time. Feel free to retry several times with at least one second between each try. If you have not done so, yet, please consider implementing backoff-retry on the client-side. If 500 appears sustained, please contact the platform operators.
502Bad Gateway. There may be a temporary unavailability or a misconfiguration on the server-side. Please retry the request at a somewhat later point in time. Feel free to retry several times with at least one second between each try. If you have not done so, yet, please consider implementing backoff-retry on the client-side. If 502 appears sustained, please contact the platform operators.
503Service Temporarily Unavailable. Your request has been rejected due to a possible overload situation on the server-side, also in order to protect the server-side from too many requests within a certain period of time, especially during an actual overload situation. Please retry the request at a somewhat later point in time. Feel free to retry several times with at least one second between each try. If you have not done so, yet, please consider implementing backoff-retry on the client-side. If 503 appears sustained, please contact the platform operators.

Appart from these, other response status codes may occur. For any 5xx response status codes, it is generally advised to perform retry, or even better, backoff-retry, on the client-side.

Next Step: Payload formats based on Google Protocol Buffers 3

Alternative: Payload formats based on JSON

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.