General methods and responses

HTTP methods

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

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

The REST API is documented in OpenAPI (Swagger) format. Access it in your browser using the IP address of the Octalarm alarm dialler, followed by /rest_api/1/. For example:

http://192.168.10.72/rest_api/1/

The /1/ in the URL indicates the REST API version. This version number remains unchanged as long as future updates are backwards compatible. Any future incompatible changes will result in a new version number.

Good to know:

1. This URL provides an overview of all APIs, including documentation;
   
   
2. You can execute or test API calls directly from this interface;
   
   
3. Each API includes a cURL command as an example. cURL is a command-line tool for retrieving or sending data, and you can use it to communicate with the REST API.

Authentication

The REST API uses a token (Bearer type) for authentication. Attach 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: You can find more information about tokens at jwt.io.

Responses

Octalarm Link responds to REST API requests with various HTTP response codes. Depending on the response, it may make sense to retry the request after a short pause if it fails.

Note: When sending a POST request to create an alarm, you must always repeat the request periodically (for example, every minute), regardless of the HTTP response code returned.

2XX

These responses indicate that the request succeeded.

• 200 OK: The request was successful.

4XX

These responses indicate that the request failed and there is no point in resending the exact same request.

Note: If the request aims to create an alarm, you must always continue repeating it periodically; even if you receive the same error each time.

• 400 Bad Request: General error status. Returned when no more specific error code applies or a limit is reached, for example, the maximum number of active alarms.
  
  
• 401 Unauthorised: The request did not include valid authentication credentials for the target resource.
  
  
• 403 Forbidden: The request was well-formed, but the REST API refuses to authorise it.
  
  
• 404 Not Found: The requested resource does not exist.
  
  
• 405 Method Not Allowed: The client attempted to use an HTTP method not permitted on the target resource.

5XX

These responses indicate a server error. In most cases, there is no point in repeating the request immediately.

Note: If the request aims to create an alarm, you must always continue repeating it periodically; even if you receive the same error each time.

• 500 Internal Server Error: A server error prevented the request from completing. This is the general REST API error message. After a brief pause, it can be sensible to retry the request.