BPAPI

BPAPI Documentation, basic concepts

Basic Authorization at the HTTP level is used. Usually email and password for a Customer is used, giving access to customer-object, gateway assigned to customer and all devices.
Some of the API-calls do not need authorization. Examples are Customer/Add and Gateway/Add.

The response is in JSON-format.
Add HTML at the end of a query to get HTML-result instead of JSON (or use ui.connome.com instead of api.connome.com).
The HTML-result will contain some additional information and links for navigating through the API

HTTP-status 200 is usually always returned (this choice is deliberate because some utilities like cURL for PHP or .NET's System.Net.WebClient will not download the HTTP response body for status codes greater than or equal to 400. This in turn would make it very difficult to communicate error messages to the client)
Every API call will return a field bpapi_status (short status) and bpapi_message (longer explanation). bpapi_status will contain "ok" or an error-status ending with _error. An error-status is usually complemented by bpapi_documentation_url pointing direct to the relevant documentation. Example of statuses are (list is not complete):

bpapi_statusMeaning
ok 
client_errorQuery was not syntactically correct
access_errorQuery not syntactically correct but access was denied (note that access-restrictions are usually not checked at the API-level but at the HTTP-level with Basic Authorization so this status seldom occurs)
data_errorQuery was syntactically correct but corresponding data was not found in the database or existing data was inconsistent with query
tcpip_errorSome kind of problems with the Gateway, communication with the Gateway (for Gateways connected directly by TCP/IP) or other partner services like SOAP/HTTP
exception_errorInternal BPAPI error. These errors should be reported back to us at Sikom Connect AS for further analysis

BPAPI is to some degree modelled on REST but not all HTTP methods are used. In principle GET may be used exclusively.
Verbs in the name of API-methods are used to indicate creation, like Customer/AddProperty.
Verbs are also used to indicate commands, like Device/TurnOn.
POST may usually be used for creation and sending of commands if so desired.
Data is not deleted or updated in the traditional sense so HTTP-methods DELETE and PUT are not used.
The equivalent of deletion is to mark a property as no longer current with Property/SetNoLongerCurrent.
Updates are done by just adding a new property with the same name.
In this manner all history is conserved, see for instance Property/History.

Parameters are usually inserted REST-style into the URL, like Property/42/Refresh (called Syntax1, GET1) but may also be added to the end like Property//Refresh?id=42 (called Syntax2, GET2).

Please note that if you want to POST data you will have to use Syntax2 (none of the parameters may be included in the URL due to a quirk in the .NET WebAPI-technology that we use).

Please also note that standard URL-encoding of parameters does not always work for GET1-syntax. You may encode with strings like _PLUS_, _DASH_, _SLASH_ and _COLON_ instead, or just consider using GET2-syntax or POST. Please consult our numerous examples for more information.



Automatically generated from BPAPI source-code 2020-04-05 01:17

Assembly built at 2020-04-01 12:26