General methods and responses

HTTP methods

As with any REST API, you use:

• GET requests to retrieve data;
• POST and PUT requests to add or overwrite data;
• DELETE to delete data.

All requests and responses use JSON objects and arrays as the data format.

The REST API is documented in the OpenApi (Swagger) format. It can be retrieved in a browser at the IP address of the Octalarm alarm dialler followed by /rest_api/1/. For example:

bash http://192.168.10.72/rest_api/1/

The /1/ in the URL is the version number of the REST API. As long as REST API requests are expansion compatible in the future, this version number will remain unchanged. Incompatible expansions are added to a new version number.

Good to know: via this URL
1. you will find an overview of all APIs, including documentation;
2. it is possible to execute or test the APIs;
3. you will find the cURL command with each API. cURL is a command-line tool for obtaining or sending data and can be used to communicate with the REST API.

Authentication

The REST API uses a token (Bearer type) to authenticate the REST API link. The remote device attaches the token as an HTTP header with every API request.

Example:

GET /rest_api/1/Interface/RestApiLimits HTTP/1.1 Host: 192.168.10.72 Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTY2OTg5MDk2NiwianRpIjoiMDUyMzJmZjAtZjJjZC00NTdlLTlmYTUtOGExMjY1OTY2NjQxIiwibmJmIjoxNjY5ODkwOTY2LCJ0eXBlIjoicmVmcmVzaCIsInN1YiI6IlJFU1QtQVBJXzAwMDUiLCJ1c2VyX2lkIjo3LCJyb2xlX2lkIjo1LCJsYW5ndWFnZSI6Im5sLU5MIn0.hp9hictrwsLW5W2G3XFKPMqChf0\_0oXxcSoWGpmZF-A

Good to know: more information on tokens is at jwt.io.

Responses

Octalarm Link can beat a REST API request with various HTTP response codes. Depending on the HTTP response, it makes sense to retry the request (after a short pause) if it failed.

Note: a POST of an alarm must always be repeated periodically (e.g. every minute), no matter what HTTP response code you get back.

2XX

This group of responses indicates that the request was successful.

• 200 OK: request succeeded.

4XX

This group of responses indicates that the request failed and there is no point in making the exact same request again.

Note: if it is a request for an alarm, you must always keep repeating it periodically; even if it is the exact same request.

• 400 Bad Request: general error status. Used when there is no specific error code that is more appropriate or when a limit has been reached, e.g. a maximum number of active alarms.

• 401 Unauthorised: the request was not applied because valid authentication credentials for the target resource are missing.

• 403 Forbidden: the client’s request is correctly formed, but the REST API refuses to authorise it.

• 404 Not Found: the requested resource was not found.

• 405 Method Not Allowed: the client tried to use an HTTP method that the source does not allow.

5XX

In this group of responses, there is usually no point in making the same request again.

Note: if it is a request for an alarm, you must always keep repeating it periodically; even if it is the exact same request.

• 500 Internal Server Error: there was an error on the server that caused the request not to complete. This is the general REST API error message. In case of a 500 server error, it makes sense to rerun the request after a short pause.