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>