2. HTTP API General Description
2N® Helios IP HTTP API (Application Programming Interface) is an interface designed for 2N Helios IP remote control, configuration and data retrieval via third party applications. 2N® Helios IP API enables 2N intercoms to be integrated in extensive user infrastructures (home automation, attendance control systems, etc.).
2N® Helios IP HTTP API provides a simple interface based on standard protocols (SOAP/HTTP), which helps read out state or statistic information.
2N® Helios IP HTTP API is defined through a web service available at:
- http://helios_ip_address/automation – 2N® Helios IP control commands;
- http://helios_ip_address/notification – log data retrieval commands.
Send an HTTP request including a properly formatted SOAP/XML data to one of the above mentioned addresses. 2N Helios IP executes the requested operation and sends back a SOAP/XML response.
The general structure of the HTTP request is as follows:
POST /... HTTP/1.1 Host: ... Content-Type: application/soap+xml Content-Length: ... <?xml version="1.0" encoding="utf-8"?> <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Header> additional control information of request </s:Header> <s:Body> request parameters </s:Body> </s:Envelope>
If the request is processed successfully, 2N Helios IP sends the following HTTP response:
HTTP/1.1 200 OK Content-Type: application/soap+xml Content-Length: nnn <?xml version="1.0" encoding="utf-8"?> <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Header> additional control information of response </s:Header> <s:Body> Response parameters </s:Body> </s:Envelope>
If the request cannot be processed or an error occurs during processing, 2N Helios IP sends the 400 Bad Request reply including SOAP/XML data with error identification.
HTTP/1.1 400 Bad Request Content-Length: ... Content-Type: application/soap+xml <?xml version="1.0" encoding="UTF-8"?> <s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:ter="http://www.onvif.org/ver10/error"> <s:Body> <s:Fault> <s:Code> <s:Value> error code </s:Value> <s:Subcode> <s:Value> error subcode </s:Value> </s:Subcode> </s:Code> <s:Reason> <s:Text xml:lang="en"> error cause details </s:Text> </s:Reason> <s:Detail> <s:Text> additional error details </s:Text> </s:Detail> </s:Fault> </s:Body> </s:Envelope>