API client

This article explains how to create an API client for consuming the Nureva® local APIs.

📘

Already know the basics? See additional information specific to the APIs at the end of this article.

Instructions

Background

Nureva local APIs follow a client-server software pattern, where the server has resources and a client is required to gather or change resources on the server. After setup of the Nureva HDL310 or HDL410 device, the server will be automatically created and live embedded within the device.

As a developer looking to gather resources from the server, you will need to create your own client with your preferred software language to call one of the server's endpoints.

Client-server communication is done through HTTP and HTTPS.

Request format

When communicating to the server, the client will send a request, and after a short delay the server will return a response. For these APIs, there are several pre-defined headers which must be included in the request, and they are endpoint specific. The capabilities endpoint, for example, is one which does not require the Authorization header that many of the other endpoints do.

These headers are required by the Nureva device. If they are not added, you will get an HTTP response code 400.

• Nureva-Client-Id: This should be unique to identify the client making the request. The same value should be used for each request made by that same client.
• Nureva-Client-Version: This will identify which version of your integration relates to the Nureva-Client-Id.

For example, Get Audio Settings has the verb GET, an optional JSON request body, and general authorization.

Response format

The response that the server will return has two important components: the status code and the response body. Status codes match common HTTP status codes. A response of 2XX means that for the request, the action taken by the server was successful. The response body is dependent on which endpoint you are calling. For most endpoints, the response body will be in JSON format or there will be no body. For the sound location endpoint, the response will be a stream of server-sent events (SSE) which can then be consumed by the client one at a time until the client closes the stream or the server is disconnected from the client.

For example, Get Audio Settings will return a JSON response body. More information can be found under the API reference section.

Additional information

1. For HTTPS, ignore any SSL errors. The server is configured to use a self-signed certificate. This will cause certificate errors. It is safe to ignore them and move on.
2. For HTTP and HTTPS, it is safe to call the server directly, without specifying any port.
3. Some endpoints return a stream of server-sent events (SSE). Clients will automatically receive updates from the server as events unfold. Usually, multiple events will occur and be pushed to the client, so do not close or send multiple endpoint calls.
4. The server has a rate limit of 600 requests per minute for endpoints that do not return a stream of server-sent events and a rate limit of 60 for endpoints that do. A status code of 409 will be returned in the event that the rate limit is exceeded.
5. Local APIs will not work with mock devices.

✅

Tutorial complete!

You now know how to consume Nureva Local APIs.