[Fiware-ngsi] Feedback welcomed: Orion Context Broker NGSI API enhancements

[Fermín Galán Márquez]

Hi,

We are about to start the development of some NGSI API enhancements in Orion Context Broker, based on users' feedback, with the aim of making the API easier and more useful for them. Those changes are mainly related with convenience operations and are backward compatible (i.e. existing client implementation will continue to work after the changes). An overview of these modifications follows.

Base URLs modification

Currently, we are using "/ngsi9" and "/ngsi10" for the NGSI9 and NGIS10 operations, respectively. However, we have found that these prefixes tend to confuse users (they usually think that "ngsi10" is the newer version of the API and "ngsi9" the former version), so we will introduce the following simplification:

  *   The NGSI10 operations (which are the most used) will not use any URL prefix.
  *   The NGSI9 operations will use the "/registry" prefix.

In addition, we will introduce versioning in the API, so in the future we can define new versions of the API (potentially backward incompatible with the current one) easily. We will use the "v1/" token as prefix, so, at the end, the base URL will be:

  *   "<server_root>/v1/" for NGSI10 operations
  *   "<server_root>/v1/registry" for NGSI9 operations

Existing "<server_root>/ngsi9" and "<server_root>/ngsi10" will continue to work (to maintain backward compatibility) as alias of the above ones.

Types and subscription listing operations

Users have reported that they miss some operations to list existing types and subscriptions, which are very important when developing general purpose web-based client front ends for Context Broker. To that end, we have defined the following operations:

  *   GET <server_root>/v1/contextTypes, to get a list of all entity types
  *   GET <server_root>/v1/contextTypes/<type>, to get the attributes of a given type (actually, NGSI doesn't forces entities of the same type to have the same attributes, thus this operation actually returns the union set of the attributes of the entities of the given type).
  *   GET <server_root>/v1/registry/contextTypes, to get a list of all registered entity types
  *   GET <server_root>/v1/registry/contextTypes/<type>, to get the attributes of a given registered type (actually, NGSI doesn't forces registered entities of the same type to have the same attributes, thus this operation actually returns the union set of the attributes of the entities of the given type).
  *   GET <server_root>/v1/contextSubscription, to get a list of all context subscriptions
  *   GET <server_root>/v1/registry/contextAvailabilitySubscription, to get a list of all context availability subscriptions

Operations on the resource "root"

REST-APIs supporting the operation "GET /foobars/<id>" for reading a resource also use to support the "POST /foobars" to create a "foobar" resource. In order to fill that gap, we wil introduce the following operation:

POST <server_root>/v1/contextEntities

(This will add to the existing "POST <server_root>/v1/contextEntities/<id>" as alternative to create entities. Both will be supported).

Moreover, REST-APIs supporting the operation "GET /foobars/<id>" for reading a resource also use to support "GET /foobars" to get a list of all the "foobar" resources. Thus, we will introduce this operation to get all entities:

GET <server_root>/v1/contextEntities

Similarly, for the NGSI9 part of the API, we will add the following:

GET /v1/registry/contextEntities
POST /v1/registry/contextEntities

These new POST operations will involve some slight modifications in the payloads (eg. appendContextElementRequest) to include entity id and type, but we think these modifications will be quite straighforward.

Filters

REST-based APIs use to support filters in read operations as URI parameters. The ability to do filtered queries/discovers is essencial for users.

GET <server_root>/v1/contextEntities?<filters>

The concept of filtering is easily extensible and for a first release we consider the following ones:

  *   id, matching entity ID
  *   type, matching entity type
  *   attribute_temperature, attribute_pressure (for the attributes temperature and pressure, respectively), etc.

With the following operators:

  *   =     equals
  *   ^=     partial matching
  *   !=    diff
  *   <    less or equal
  *   >    more or equal
  *   !<    less
  *   !>    more
  *   <>    range

Eg. query for the entities of type "sensor" which temperature is greater than 30 and status is not "error"

GET <server_root>/v1/contextEntities?type=sensor&attribute_status!=error&attribute_temperature>30

Filters in the convenience operations will map to Restriction in the corresponding mapped queryContext or discoverContextAvailability operation. We need to work on the details of this mapping yet.

Entity type inclusion in URLs

One limitation in the current convenience operations API is that they don't allow to specify the type of the entity in the URL. However, in many cases, the user wants to refer to an specify type.
Thus, from now on operations such as:

...contextEntities/<id>
...contextEntities/<id>/attributes/<attr>

will allow two different possibilities:

  *   <id> is <entityId> (as in current implementation), eg:
     *   ...contextEntities/365
     *   ...contextEntities/365/attributes/name
  *   <id> is "/type/<entityType>/id/<entityId>", eg.:
     *   ...contextEntities/type/Car/id/365
     *   ...contextEntities/type/Car/id/365/attributes/name

In some way, this is a mechanism to consider "namespacing" for the entity using and "expanded" ID (beyond just the entity ID literal). Thus, within the "name space" of all entitis with type "Car" we are looking for the one with ID equal to 365.


In sum, we think that the above additions and changes doesn't break existing clients implementations and they will enhance the FIWARE NGSI API binding. We propose to modify the FIWARE NGSI API documents to include them. What do you think?

Any feedback is welcome!

Best regards,

------
Fermín

PD. My colleagues in CC are algo involved in NGSI in Telefonica I+D. Please, keep them in CC if you reply to this CC.

________________________________

Este mensaje y sus adjuntos se dirigen exclusivamente a su destinatario, puede contener información privilegiada o confidencial y es para uso exclusivo de la persona o entidad de destino. Si no es usted. el destinatario indicado, queda notificado de que la lectura, utilización, divulgación y/o copia sin autorización puede estar prohibida en virtud de la legislación vigente. Si ha recibido este mensaje por error, le rogamos que nos lo comunique inmediatamente por esta misma vía y proceda a su destrucción.

The information contained in this transmission is privileged and confidential information intended only for the use of the individual or entity named above. If the reader of this message is not the intended recipient, you are hereby notified that any dissemination, distribution or copying of this communication is strictly prohibited. If you have received this transmission in error, do not read it. Please immediately reply to the sender that you have received this communication in error and then delete it.

Esta mensagem e seus anexos se dirigem exclusivamente ao seu destinatário, pode conter informação privilegiada ou confidencial e é para uso exclusivo da pessoa ou entidade de destino. Se não é vossa senhoria o destinatário indicado, fica notificado de que a leitura, utilização, divulgação e/ou cópia sem autorização pode estar proibida em virtude da legislação vigente. Se recebeu esta mensagem por erro, rogamos-lhe que nos o comunique imediatamente por esta mesma via e proceda a sua destruição
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.fiware.org/private/fiware-ngsi/attachments/20140925/059efe73/attachment.html>