|
<< Click to Display Table of Contents >> Navigation: The API > API Overview > API function calls |
API functions calls
The API is the central Interface for the IP clients to connect to EnOcean devices. When designing the API, one should choose an implementation that is based on common modern standards which offers a solid basis for future EnOcean devices as well as for the transition to the Internet of Things.
A RESTful specification of the IP Interface enables many IP clients on the REST API to operate in parallel, each of which may have set his individual preferences with the Interface.
The connection between IP - Client and the IP-Interface is established via HTTP requests which are divided into five main functional groups:
Profile functions allow a query of the Interface regarding profiles (EEP) and their functions (representation) without corresponding devices available or taught in.
Device functions are used to get an overview of the taught-in devices of the Interface. This includes the list of devices, their current states and the query for each device, which functions it enables and how to address them. These device functions are similar to the profile functions, except that they relate to real devices and their interaction.
The device functions also include functions that allow you to manage, teach-in and delete the devices into the Interface. These functions must be especially secured, because they reflect a base functionality.
•Transmission functions
The transmission functions are the main features for the regular operation of the Interface.
With the PUT function, commands are transmitted to the Interface which should be executed in the EnOcean world.
The GET function enables the client to be notified of changes on the EnOcean side. In order to transfer events of EnOcean devices in real-time to the connected IP clients, a permanent connection must be kept open between the Interface and the respective client. This is achieved in the REST API via a streaming functionality where the gateway as well as the client do not close their connection on a certain HTTP-Endpoint. (Streaming, chunked transfer encoding)
The system functions provide direct control of the Interface. These include querying the system information and the switching of the EnOcean chip to learn-in or normal mode either.
•Help functions
The Interface should show a clear and comprehensive overview of all available functions on the REST API at root level. The codepage to be used is be „UTF-8“