General API Specification

The REST API provides programmatic access to read, write and command the system data and functionality. The API identifies users using OAuth (RFC 6749); responses are available in JSON (RFC 4627).

HTTP Methods

Following REST principles, one can call the following HTTP methods on the API resources: GET, POST, PUT, and DELETE.

Method (HTTP Verb)	Description
GET	Retrieves a list of resources, or a specific resource.
POST	Creates a resource, passes in a parameter, or performs an action on a resource.
PUT	Updates an existing resource.
DELETE	Deletes an existing resource or subscription.

Resources

The Web Service Interface API follows REST principles and therefore exposes data and functionality as resources.

Every resource is represented as a URI. As a summary a resource looks like the following:

scheme://domain:port/path?query

Part	Description
scheme	Usually HTTPS; HTTP should only be used for testing.
domain	Hostname of host where the manager is running.
port	Usually 80 for HTTP and 443 for HTTPS.
path	Starts with api followed by the service-identifier and optional sub-paths (e.g. api/languages/en-us); see sections below.
query	Optional; depends on resource (see sections below).

Examples:

https://computer1:443/alertws/api/v1/alarms?offset=0&limit=20
https://www.example.com/alertws/api/v1/alarms?offset=0&limit=20

Therefore, the general format of a URL is:

{entry-point}/api{resource-address}

Where entry-point is http://[hostname]:[port] by default or dependent on the deployment, and resource-address in EBNF is:

resource-address = path [ "?" query ]
path             = /root-resource | path "/" sub-resource
query            = parameter { "&" parameter }
parameter        = key [ "=" value ]

Status Codes

HTTP Status Codes

Status Code	Meaning	Description
200	OK	Request processed.
400	Bad Request	Request rejected by application.
401	Unauthorized	Invalid or expired token presented (User needs to login).
403	Forbidden	Request is not permitted (Access right).
404	Not Found	Resource couldn't be found for the provided URL and query parameters.
408	Timeout	Request didn't be managed in allotted timeout period.
500	Internal Error	Unexpected error appeared.

Encoding

Data is encoded in UTF-8.

Array in Query Parameter

In case a query parameter represents an array, the array is passed as a JSON array.

Example:

someurl?Ids=[1,2,3]