General Model

Intro

Sentilo offers an open source API based on REST interfaces.

Representational State Transfer (REST) is a style of architecture that exploits existing technologies and protocols of the World Wide Web (WWW).

The communication from external elements with Sentilo will be through HTTP protocol (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 observation(data).
  • Component: corresponding to a element of hardware or software, with geospatial 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 communicate with Sentilo for sending data and receive commands.
  • Client application / Module: entity that consumes the data processed by the platform.

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 specified for each services.

Representations

Data formats that will supports the platform is currently only JSON.

Example data in JSON format:

{"observations":[
    {"value":"12.3","timestamp":"17/09/2012T12:34:45"}
]}

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.

Response

The response to a request to the platform is managed through the response HTTP status codes.

Error Code HTTP Description
200 Success Request accepted and processed correctly
4xx Client Error Error in request (Wrong format, forbidden mandatory parameters, …)
401 Unauthorized Unauthorized request: empty or invalid credential
403 Forbidden Not authorized for the requested action
404 Not Found The requested entity does not exist
429 Too Many Requests Global quota or entity quota exceed
5xx Server Error Error processing the request

In case of error the response body will include a description of the problem detected, 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: Unexpected character ('o' (code 111)): ....."]
}