Consuming the API

Given the nature of the data exposed through Noa's API, there are different consumption patterns for different usecases. Based on parameters such as how often information is requested, or if updates should be processed in real time.

For example, your operations and security crew might be interested in requesting trips for specific bicycles on demand, a few times a day. Or you may want your system to respond promptly to critical alerts as they happen. Or your users would want to receive updates about a bicycle they are about to rent.

Consumption Patterns

To satisfy these necessities, this API includes three main forms of consumption, classified as push and pull strategies for convenience purposes.

Request / Pull

This approach takes the form of HTTP requests, and is meant to be the norm when accessing resources exposed by the API. Requests are issued when new information is needed by your system, and a response containing the requested content is returned.

For example, to retrieve the current state of bicycles, including their GPS positions, simply issue a request to the bicycle endpoint, such as:

GET /bicycles/
Authorization: JWT <token>
Accept: application/json;version=1.0

Push

Use this strategy when your system needs to be notified or updated with new information as soon as it's generated. This allows your applications to remain on hold, waiting to consume new elements being pushed from Noa's API.

There are two forms of push technologies supported, each of them suited for very concrete purposes.

Server-Sent Events (SSE)

Server-Sent Events is a mechanism that allows for server-to-client unidirectional and asynchronous delivery of events. SSEs are part of the HTTP protocol and supported by most browsers and HTTP clients.

This technology is well suited for clients that need continuous updates on concrete resources without the extra overhead that strategies such as polling or technologies like Websockets bring. In addition to that, headers and authentication mechanisms apply to SSE just as they do for regular HTTP Requests.
For example, SSEs are a great fit to consume real time updates on bicycles.

With SSE, your client creates a connection through our APIs against a topic of interest using a GETrequest on the subscription endpoint (/subscribe/<topic>/). Upon successful establishment, new updates will flow through the channel in real time.

Notes about the topic path segment

• Topics need to be properly encoded according to W3C URL standards, with no safe characters, i.e. also slashes in the topic itself need to be encoded (you could use urllib.parse(topic, safe="") in Python).
• The slash suffix is required.

For example, to receive updates about your bicycles, establish a connection with the following endpoint:

GET https://sse.noa.one/subscribe/%2F{organization_uuid}%2Fadmin%2Fbicycles%2F%2A/
Authorization: JWT <token>

The topic for this example is: /{organization_uuid}/admin/bicycles/*

If you want updates on a particular bicycle it will look like this:

GET https://sse.noa.one/subscribe/%2F{organization_uuid}%2Fadmin%2Fbicycles%2Fae4469fe-b4c8-4a36-9c60-232e4b56c2df%2F/
Authorization: JWT <token>

The topic for this example is: /{organization_uuid}/admin/bicycles/ae4469fe-b4c8-4a36-9c60-232e4b56c2df/

Messages are formatted as JSON documents with the following structure:

Clients

There are numerous clients to consume SSE-enabled resources, that cover a wide range of programming languages, including Java, Swift, Python, PHP, Javascript, Go, Erlang and others.

Pagination

Pagination links are provided as part of the content of the response.

Pagination accepts a single number page in the request query parameters.

GET https://api.lock8.me/api/bicycles/?page=4

You will find the navigation links in the response as follows:

{
    "count": 1023
    "next": "https://api.lock8.me/api/bicycles/?page=5",
    "previous": "https://api.lock8.me/api/bicycles/?page=3",
    "results": [
       …
    ]
}

X-Noa-Headers

Responses coming from this API include a set of custom headers to help us identify and trace requests inside of our system. Do make use of them when facing issues and contacting our team to troubleshoot specific requests.