HTTP-XML - REST Migration guide

This page describes how to migrate from our existing XML based API to the new RESTful API.

Using an OAuth token instead of the session id

The first big difference between the old and new API is the usage of OAuth for authentication.

With the old API you logged in with your credentials and received a session id which was valid for a certain amount of time. The session could be extended by usage of the ping API call.

With the new API you will receive an access token after logging into the system. With this token you will be able to perform subsequent API calls.

Besides the access token you will receive the token type, scope, an 'expire_in' value and a refresh token. The token type and access token must be set in the 'Authorization' value of the header of the subsequent API calls. The scope defines the permissions in the API calls and can be one of 'read' or 'write'. The 'expire_in' value is the number of seconds after which the access token will expire. With the refresh token you will be able to retrieve a new access token.

Using the old API together with the new API

During development not all API calls will be available just yet within the new REST API. Also to allow you to use both API's during the migration process we created a REST API call to create a session id and user id which are needed to use the existing API's.

XML versus JSON

The current API returns content in XML format while the new API returns this data in JSON format.

HTTP methods

With the XML API you used the GET and POST methods to retrieve and/or set properties of users, cameras, zones etcetera. The response where XML formated messages with the returning data or error codes and messages.

Method Operation Description
GET Read Retrieve the resource and returns it in a JSON structure. Response code is 200 for successful retrieval or 404 if the resource not found.
POST Create Creates a new resource based on the posted body content.
PUT Update Updates the resource based on the identifier and content within the posted body.
PATCH Modify Partially update of the resource.
DELETE Delete Removes the resource.

Response codes

With the XML API the HTTP response code is always 200 even if an error occured. The XML response contains the application response code as an attribute. When the response is OK, this code is 200. Otherwise, besides the attribute 'code' with corresponding value, the XML containts an 'Error' tag with the error messages. The response codes can be found here: Response codes.

By implementation of the REST API we use corresponding HTTP response codes to reflect the outcome of the API call.