Introduction

Nomanini has chosen a RESTful architecture for the API using JSON for data transfer.

We have standardised on the following methods and their actions:

• POST /<entity_type>/ creates a new object of type entity_type, and the object data within the body of the POST. Returns the object_id in the response body.

• PUT /<entity_type>/<object_id> updates a specific object_id with the data to be updated sent in the body of the PUT request .

• GET /<entity_type> returns a list of objects of type entity_type in the response body.

• GET /<entity_type>/<object_id> a specific object_id's data is returned in the response body.

• DELETE /<entity_type>/<object_id> removes a specific object_id.

HTTP request and response ¶

All requests are made to an HTTPS URL end point on the API. For GET requests, URL encoded parameters are passed in the URL.

For POST and PUT requests to the API, fields are passed in as a JSON object in body. The client must set the Content-Type HTTP header to Content-Type: application/json.

Responses return standard HTTP response codes. (See below for a subset of the codes.) The Content-Type header will contain Content-Type: application/json.

The body of the response will contain a JSON object, where the top level object field contains the method’s result or an errors field with a list of error messages if there was a problem processing the request. Use the errors field in the JSON response to determine what might have caused the error.

The client must wait up to 60 seconds for a response from the API. If the server cannot process the request in that time it will return an HTTP response code 500 Internal Server Error.

Headers ¶

In order to make use of Nomanini API methods, you need to supply the following request headers in every call:

X-API-Key ¶

This is the API key used to identify users and apply the correct permissions. Each user on the system has their own API key which can be found at todo:

X-API-Key: 0123456789ABCDEF0123456789ABCDEF

X-API-Version ¶

Optional. This allows you to target a specific version of our API methods. If omitted, the system will use the default, usually latest API methods:

X-API-Version: 1.0

X-Nomanini-Organisation ¶

This is your unique client identifier and will be supplied to you by Nomanini:

X-Nomanini-Organisation: yourclientid

Content-Type ¶

For POST and PUT requests to the API, fields are passed in as a JSON object in body. The client must set the Content-Type HTTP header to Content-Type: application/json.

All responses from the server will contain the correct Content-Type headers.

Optional request parameters ¶

Request parameters marked as Optional do not have to be included in requests, and if omitted the API will assume the default value.

JSON driven ¶

All request and response bodies are expressed in JSON format.

The response will as far as possible always return a named object.

{
    "<object_name>": {}
}

Error conditions ¶

When at least one error occurs, the relevant HTTP status code is set in the response header and a list of errors is returned in the response body.

Each error object contains some or all of the following fields:

• code is a text string that can be used by your application to detect the type of error. For a full list of error codes see TODO.

• developer_message is a plain language description of the problem, for developers, with hints about how to fix it.

• user_message is a message suitable for display to an end user for example, on the front end.

• more_info is a link to the Nomanini knowledge base with detailed information about this error.

• request_id is the unique identifier for this request. You may be asked to supply this identifier to the Nomanini support team to help resolve any integration issues you are having.

Example response with an error:

Status-Code: 400 Bad Request

{
  "errors": [
    {
      "code": "no_data",
      "developer_message": "There is no data for the given date range, try a larger date range.",
      "user_message": "Sorry, nothing was found.",
      "more_info": "https://nomanini.groovehq.com/knowledge_base/topics/date_range_queries",
      "request_id": "54c3c61900ff0d1d98752fb3160001737e6e6f6d616e696e692d64617368626f6172640001353430332d63303965616534666631383400010101"
    }
  ]
}

HTTP response codes ¶

If the API request was successful then the server will return HTTP status codes:

• 200 OK: Standard response for successful GET or PUT request.

• 201 Created: Standard response to a POST request.

• 202 Accepted: Request has been accepted but not fully processed yet. The result of that request can be found by doing a GET to the URL returned in the Location header.

• 204 No Content: For a GET indicates that the data requested is not yet available, and you should try again later. For a DELETE indicates that the delete was successful and there is no data to return.

• 303 See Other: Request has been accepted and the result of that request can be found by doing a GET to the URL returned in the Location header.

If there was an error processing the request then the server will return one of the following standard HTTP error status codes:

Application and client errors:

• 400 Bad Request: The client issued a request that was missing or had the wrong parameters. See the errors within the response body for details of the error and suggested fixes.

• 401 Unauthorised: The client is not logged in and needs to authenticate before accessing this method.

• 404 Not Found The API method requested does not exist.

• 405 Method Not Allowed: Client is using the wrong HTTP method for the URL endpoint.

• 409 Conflict: The client submitted a request that has already been processed.

• 413 Request Entity Too Large: The client made a request that returned more than 32 MB of data. Reduce the date range or use the limit parameter to reduce the scope of the query.

Server errors:

• 500 Internal Server Error: There was a problem processing this request.

• 503 Service Unavailable: The API is temporarily not accepting requests.

If the problem persists contact support@nomanini.com

The client should assume that any response code in the 400 and 500 range is an error and handle it accordingly.

Asynchronous workflow

Usually, a successful GET request responds with a 200 OK return code. Some requests (eg, performing a stock import, or running a report) however, will take too long to complete immediately.

In such cases the system will respond with a 202 Accepted return code, signifying that the request was accepted and the server will continue to process it in the background. At the same time, a Location header is also returned, with a URL reference, allowing the caller to poll against and subsequently get the request result.

When polling the referenced URL, the server will continue to respond with a 204 No Content return code until the server actually completes the request.

When the request completes successfully, a return code of 200 OK is returned, with the resulting information as part of the response body.

If an error occurred, the corresponding HTTP response code is returned, with more information around the actual problem as part of the response body.

Duplicate POSTs and idempotency ¶

When making requests to our API specifying a source_reference is often required. This is to ensure that the request takes effect no more than once. Your source_reference should be unique per API endpoint. source_reference's cannot be recycled.

If the source_reference is unique, and the request to the API was successful, you can expect a 200 OK response.

If the API call is made again with the same source_reference, the system will respond with a 409 Conflict along with the same response body of the previous matching API call.

Dates and times ¶

We use the ISO 8601 format for all dates and times. The seconds value may include fractional seconds to a resolution of one microsecond.

You can send times to us in any of the ISO 8601 supported formats but we recommend one of the following:

• YYYY-MM-DDTHH:MM:SSZ

• YYYY-MM-DDTHH:MM:SS+00:00

• YYYY-MM-DDTHH:MM:SS+hh:mm

where hh:mm is the signed hour and minute offset of your local timezone from UTC. (If you give us a timezone offset, we’ll convert to UTC internally.)

Dates and times are always returned in UTC and in the format YYYY-MM-DDTHH:MM:SS+00:00.

Time ranges ¶

When specifying a time range, the API will return data with a time greater than and equal to start_time, up to but not including the end_time.

For example, to get all the data for 1 Jan 2015 use start_time=2015-01-01T00:00:00+00:00 and end_time=2015-01-02T00:00:00+00:00.

Transaction time and Valid time ¶

Unless an API method specifically states otherwise, all dates and times are the times that a transaction was logged on the server, known as the Transaction time.

When a sale happens on a device, the date and time of that sale (the Valid time) is logged by the device (for example on 1 Jan.) However, that sale may only be uploaded to the server the next day (on 2 Jan), perhaps due to the device not having GSM network coverage or its battery being flat.

The server logs the time of the sale as when it was uploaded from the device to the server (on 2 Jan).

On 3 Jan, running a request for all sales using the /sales/device method for the day of 1 Jan would not return that sale, but running the request for 2 Jan would.

Caching ¶

TODO: Cache headers, how long to cache for etags, expiry times, etc