Basics of REST

As Wikipedia says:
"REST is an architectural style consisting of a coordinated set of architectural constraints applied to components, connectors, and data elements, within a distributed hypermedia system. The REST architectural style is applied to the development of web services."

"Web service APIs that adhere to the REST architectural constraints are called RESTful. HTTP based RESTful APIs are defined with these aspects:"

  • Base URI, such as https://example.com/resources/
  • An Internet media type for the data. This is often JSON but can be any other valid Internet media type
  • standard HTTP methods (e.g., GET, PUT, POST, or DELETE)

"Unlike SOAP-based web services, there is no "official" standard for RESTful web APIs. This is because REST is an architectural style, unlike SOAP, which is a protocol. Even though REST is not a standard, a RESTful implementation such as the Web can use standards like HTTP, URI, XML, etc."

Getting Started

theThings.IO API is a RESTful API that allows you to store and share real-time data generated by your Internet-connected things. In this document you will learn how to connect your networked objects at theThings.IO.

There are many things you can connect with theThings.IO REST API. Arduino, Raspberry Pi, Intel Galileo or Electric Imp are some of the DIY things that you can store their real-time data and visualize it through theThings.IO dashboard. To access theThings.IO API you need a developer account. To sign up, create an account and get your tokens from our platform: Getting Started in 59 seconds.

Tip: When you develop the firmware of your device, try not to use static buffers with fixed size to get the HTTP response, use dynamic buffers. Its size may change.

Security and Authentication

HTTPS is a layer on the top of HTTP with SSL/TLS protocol that provides authentication and bidirectional communications encryption that protects from man-in-the-middle attacks, eavesdropping and tampering. HTTP calls (without SSL support) are also accepted to and from theThings.IO REST API through api.devices.thethings.io endpoint.

We strongly recommend to use HTTPS in all your theThings.IO REST API requests.

Get tokens

To be able to follow the examples you will need an activation code or a thing token.

An activation code is a unique code that will enable your devices to be activated via the registration API call. The purpose of this code is at the same time identify you as the creator of the thing and when some day you start selling your awesome IoT product, avoid that somebody can activate things in your name. As a result of this call your thing will receive a unique thing token that will identify your thing at thethings.iO platform.
You can also activate your things manually at the Panel as explained on the getting started guide.

If you are in the developers tier you will get one activation codes for free. If you are in the premium tier you will be able to generate as many activation codes as you need. To get your tokens go to the things manager page and click the get activation codes button.

Postman Test

You can test the following queries (except thing subscribe) importing the following postman collection: thethings.iO Postman Collection

Get Postman: Postman REST Client.

cURL Test

This is thethings.iO CURL test to check that you are able to make requests.

Activate, Read, Write & Subscribe

In the examples, the (braces included) indicate variables that you may replace for the appropiate value.

At this guide, we only show the basics of the API REST, You can access to the full REST API Reference to get the full list of endpoints available.

Activate

Activates a thing with an activation code.

POST https://api.thethings.io/v2/things/
HTTP Codes Messages
201 Created
400 Bad Request

ThingWrite

Writes the records of data from the thing corresponding to the specified THING_TOKEN. Only alphanumeric characters and ".", "-", "" simbols are admited for the resource name "key".

POST https://api.thethings.io/v2/things/{ {THING_TOKEN} }
HTTP Codes Messages
201 Created
400 Bad Request

To run this examples with curl you can replace the body (-d) in the call above.

Geolocating your values

If your thing can change its location you can geolocate your values adding the geo parameter in the body.

Adding a custom timestamp

When thethings.iO receives a value, also stores the current date and time in UTC format. But sometimes your thing can't be able to send the values at the time the sensor reading was done (i.e. your thing doesn't have connectivity or you want to save battery).

To solve this use cases, you can send a batch of values and indicate the time on each. The values don't need to be sorted by time, they will be sorted by our storage system automatically.

The format is YYYYMMDDHHmmss. Notice thethings.iO considers all times to be in UTC.

You can get the server time by calling:

GET https://api.thethings.io/v2/utils/date?thingToken={ {THING_TOKEN} }&format={ {format}}

Where format can be UTC (default) or unix_timestamp

ThingRead

This method returns the values of the specified KEY from the corresponding thing THING_TOKEN.

GET https://api.thethings.io/v2/things/{ {THING_TOKEN} }/resources/{ {KEY} }
HTTP Codes Messages
201 Created
400 Bad Request
401 Unauthorized
404 Not found

Request Parameters

Parameter Default Format Description
limit 1 Number How many results (max 100)
startDate Jan 1st 1970 YYYYMMDDHHmmss The min date
endDate End of times (for JavaScript) YYYYMMDDHHmmss The max date

ThingReadAll

This method returns the values of all the resources of the corresponding thing THING_TOKEN.

GET https://api.thethings.io/v2/things/{ {THING_TOKEN} }/all_resources
HTTP Codes Messages
201 Created
400 Bad Request
401 Unauthorized
404 Not found

Request Parameters

Parameter Default Format Description
limit 1 Number How many results (max 100)
startDate Jan 1st 1970 YYYYMMDDHHmmss The min date
endDate End of times (for JavaScript) YYYYMMDDHHmmss The max date

Thing's description

There’s a special resource called description that can contain meta-data about the thing. This meta-data could be the Thing name (chosen by the user), geocoordinates, JSON objects and any other data the developer want to put there.

This resource is accesible the same way that all the resources. With the GET and PUT resource values.

Before you modify this resource, you have to get the actual description value, change the properties you want to modify and the store with a PUT the complete document again.

GET https ://api.thethings.io/v2/things/{ {THING_TOKEN} }/resources/description
PUT https ://api.thethings.io/v2/things/{ {THING_TOKEN} }/resources/description

ThingSubscribe

This method subscribes to the thing channel and gets realtime updates. You will need a compatible client. To subscribe from a browser we recommend to use Websocket. REST API subscription is not reliable on browsers.
GET https://api.thethings.io/v2/things/{ {thingToken} }?keepAlive=60000
HTTP Codes Messages
201 Created
400 Bad Request
401 Unauthorized

Examples

Node.js

The next Node.js library allows to easily connect to the api.theThings.io

You can visit the github repository: theThings.IO API REST Node.js library

And get the examples at: theThings.IO API REST Node.js examples

Arduino

See the examples to connect your Arduino to thethings.iO at our GitHub Repository for Arduino Examples