Overview

Introduction

Welcome to the Thingful API. You can use our API to search for and retrieve data on all of the IoT objects currently indexed by Thingful.

Our API is designed to follow standard RESTful design practices featuring predictable resource-oriented URLs and to use standard HTTP response codes to indicate errors.

We currently don’t have any language bindings, so examples are shown simply using cURL[1] from the command line.

Versioning

We strive not to release any breaking changes to the Thingful API, but over time the public API must change and evolve in response to changing requirements of clients or new functionality being added. To minimise the impact of any changes, clients consuming data from the Thingful should send a special version parameter with all requests. This parameter defines a timestamp in YYYYMMDD form, which indicates the most recent version of the API the client application is capable of consuming.

This parameter can either be supplied via a version query parameter, or it can be specified by means of the custom HTTP header: X-Thingful-Version.

Important

If the version parameter is omitted, then Thingful will default to treating the request as being for the latest available version of the API, which might include changes that break your client, so we recommend clients should include this parameter.

For example a complete request to the API including a version parameter might look like this:

Responses will include a special X-Thingful-Version header indicating the version of the API used when generating a response.

GET https://api.thingful.net/things?version=20160301

To clarify let’s illustrate this with the following example:

  • Let’s say hypothetically Thingful has released the following incompatible API versions: 20151203, 20160418 and 20160809.
  • A new client application is created and released on 3rd March 2016, and to ensure maximum stability the programmer of this client application ensures that all requests made to the Thingful api include the following version string: 20160303.
  • This version string is not an exact match for any of the versions specified on Thingful’s side, but this does not matter; Thingful will handle the request with the most recent API version less than or equal to the version specified in the request parameter, so in this case this would be the 20151203 version.

Note

At no point does the client ever need to know the specific versions that Thingful has released, as long as they send a consistent version string, their application will continue to work stably.

Current Version

The Thingful API is currently under heavy development, and no guarantees can be made that changes will not be made to the API outlined in this document. As soon as we reach a point of feature stability, we will specify the first official release version.

Transport Protocols

All requests to the Thingful API can currently be made over either http or https. We strongly recommend using the https endpoint if your client can support it, which it almost certainly will. The only clients that might have a problem with https would be low powered devices like an Arduino.

Data Protocols

The Thingful API currently exposes it’s data via two protocols: JSON API and Hypercat. Both specifications are basically JSON documents over HTTP, but where they differ is that Hypercat is very much intended to be a simple discovery mechanism by which IOT resources can be listed as a first step to making use of these resources, whereas our full API provides richer capabilities for interacting with the resources listed.

JSON API

JSON API is a relatively new set of conventions for designing RESTful JSON based APIs over HTTP. It specifies a minimal set of conventions describing how data should be structured and made available, which in theory allow developers to take advantage of generalised tooling for consuming these APIs and allow them to focus on actually doing something useful with the data.

Full details of the specification are available on the JSON API website here: http://jsonapi.org/format/.

Hypercat

Hypercat is a JSON based hypermedia catalogue format designed for exposing information about IoT assets over the web. It was conceived and is now supported by a large consortium of significant players in the Internet of Things (IoT) industry, and its stated goal is to promote interoperability between disparate vendors and service providers.

The latest version of the standard can be found here: http://www.hypercat.io/standard.html, but for more details on how we are implementing Hypercat please see our Hypercat implementation.

Authentication

Not every request to the Thingful API requires authentication; for example simple search requests for Things or requests for the Thingful Hypercat can be made without providing any credentials. However for endpoints where access requires specific permissions authentication credentials can be sent in two different ways:

  • HTTP Basic Authentication
  • JSON Web Token (sent in a header)

Some requests that require authentication will return 404 Not Found instead of 403 Forbidden where returning a 403 Forbidden might leak information on private resources to unauthorised clients.

Basic Authentication

Provided you have added a password associated with your account you can make requests to the API by sending your username and password via HTTP Basic authentication.:

curl --user username:password "https://api.thingful.net/"

JSON Web Token (sent as a header)

You can make authenticated requests by sending a JWT in the Authorization header using the Bearer schema.:

curl -H "Authorization: Bearer JWT" "https://api.thingful.net/"

JSON Web Tokens (or JWTs) can be obtained either via the /login or /tokens endpoints described below.

Schema & Date Format

The Thingful API returns all requested data as JSON, including error messages.

Blank fields in response bodies will be always included, and will be returned with a value of null if they are a simple value. If they are an array type they will be represented as the empty array: [], or if they represent a nested JSON object they will be an empty object: {}.

All timestamps will be returned in the standard ISO8601 format including milliseconds, e.g. YYYY-MM-DDTHH:MM:SS.sssZ

Root Endpoint

You may issue a GET request to the root endpoint of the API to receive a JSON body containing all of the endpoints supported via the API. This is intended to make the API as intuitive and ‘explorable’ as possible for users wishing to build something using the API.

$ curl https://api.thingful.net/

HTTP Status Codes

The Thingful API attempts to use standard HTTP status codes. In general responses in the 2xx range indicate success, codes in the 4xx range indicate an error on the client side (e.g. missing or incorrect parameters or invalid request bodies), and codes in the 5xx range indicate an error in the Thingful servers.

Response Code Meaning
200 OK Request succeeded, response is included
204 No Content Request succeeded, no response body has been sent
400 Bad Request Client error, often a missing or incorrect parameter
404 Not Found Server unable to locate specified resource
422 Unprocessable Entity Client error, often a malformed JSON body
500 Internal Server Error Some unexpected error happened in the Thingful server stack
502 Bad Gateway One or more of the services Thingful depends on is unavailable
503 Service Unavailable The main Thingful API server is temporarily down

Errors

In general the Thingful API attempts to return HTTP status codes that correlate with any errors, but to aid debugging for 4xx errors where the client can reasonably expect that an amendment to their request might resolve the problem, we also return a JSON body containing some additional information about the problem.

An example error response might look like this:

HTTP/1.1 400 Bad Request
Content-Length: 200
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "status": "400",
      "title": "Invalid query parameter",
      "detail": "Value must be less than 500"
      "source": {
        "parameter": "limit"
      }
    }
  ]
}

Time Zones

Currently the Thingful API returns all timestamps in UTC.

Cross Origin Resource Sharing (CORS)

The Thingful API supports simple CORS as every response currently includes the required Access-Control-Allow-Origin: * header which means that any resource can be accessed by any domain in a cross-site manner

Content Types

All content published by the Thingful API will have one of two content types:

application/vnd.api+json
This is the standard content type mandated for server implementations that conform to the JSON API standard.
application/vnd.hypercat.catalogue+json
This content type is required MIME type for Hypercat documents, and will be returned for all clients interacting with our Hypercat endpoint.

Both of the above mime types describe a JSON document format.

Footnotes

[1]cURL or curl is an open source command line tool and library for transferring data across the network. It supports a huge range of protocols, but we’re just using it as a tool for making HTTP requests from the command line. If you have an OSX or Linux machine you probably already have curl installed on your system, windows users will have to work harder to install it. See: http://curl.haxx.se/