General Model

Contents
Intro
Resources
Identifier
Representations
JSON format
XML format
Operators
Reply
Intro
Sentilo offers an open source API based on REST interfaces.
Representational State Transfer(REST) is a style of architecture that exploits e
xisting technologies and protocols of the World Wide Web (WWW).
The communication from external elements with Sentilo will be through HTTP prot
ocol(Hypertext Transfer Protocol).
Here, briefly describes the concepts of REST terminology that Sentilo will use:
Resources: Elements of the information system.
Identifiers: Unique name that identifies a resource within the system.
Representations: Format of the exchanged data.
Operations: Actions that can be performed on a resource.
Response codes: Result of the operation.
Resources
Resources, or pieces of information of Sentilo Platform, are:
Sensor: item of hardware or software with the ability to generate an observa
tion(data).
Component: corresponding to a element of hardware or software, with geospati
al location (fixed or mobile) who could be composed by 1 or more Sensors.
Provider: entity that represents a grup of components and allows them to com
municate with Sentilo for sending data and receive commands.
Client application/Module: entity that consumes the data processed by the pl
atform.
The actions that can be carried out are:
Applications/modules:
Register on the platform, but always from the administration console.
Send orders to providers/sensors (order service).
Receive data from provider/sensors (data service).
Subscribe to system events (subscribe service).
Providers/sensors:
Register on the platform (catalog service).
Subscribe to system events (subscribe service).
Publish data (data service).
Sensors and components have always a an associated typology.
Identifier
Unique name that identifies a resource in the system.

In the case of Sentilo, it is an URLs (Uniform Resource Locator).

The base URL is composed as follows:
protocol://domain:port/service
and consists of the following parts:
Communication protocols: HTTP or HTTPS.
domain: Platform server API domain (e.g. localhost).
port: Port defined for communications with the server API (e.g. 8081).
service: catalog, data, order, etc..
Every service has a custom URL format as especified for each services.
Representations
Data formats that will support the platform are: JSON (initial version) and XML
(in a future releases)..
The default format used by the platform is JSON.
To specify a different format, you must add the parameter
s shown in the following example:

format in the request, a

http://<your_api_server.com>/service/<id_provider>?format=XML
JSON format
Example data in JSON format:
{"observations":[
{"value":"12.3","timestamp":"17/09/2012T12:34:45"}
]}
XML format
Example data in XML format:
<observation>
<value>12.3</value>
<timestamp>17/09/2012T12:34:45</timestamp>
</observation>
Operators
The platform operators are the HTTP protocol methods.
In general, the operation associated with the operations used by Sentilo are:
GET: Request information.
POST: Send new data.
PUT: Update existing data.
DELETE: Erase data.
The platform discriminates the action you want perform from the method used and
by the service, provider or sensor specified in the URL invoked.
Reply
The response to a request to the platform is managed through the response HTTP s
tatus codes.

Error Code
HTTP
200
Success Request
4xx
Client Error
meters, ...)
401
Unauthorized
403
Forbidden
5xx
Server Error

Description
accepted and processed correctly
Error in request (Wrong format, forbidden mandatory para
Unauthorized request: empty or invalid credential
Not authorized for the requested action
Error processing the request

In case of error the response body will include a description of the problem det
ected, as shown in the following examples:
This payload is returned when no credential is sent:
{"code":401,"message":"Invalid credential null"}
This payload is returned when JSON payload could not be read as JSON:
{"code":400,
"message":"SIE03-1398350628224 Bad request data: could not read JSON payload.
Please review the following error and try again",
"errorDetails":["org.sentilo.common.exception.MessageNotReadableException: Unex
pected character ('o' (code 111)): ....."]}