[Fiware-ngsi] FIWARE NGSI API v2

[Fermín Galán Márquez]

Dear Tobias,

Please find my comments inline.

El 16/06/2015 a las 11:55, Tobias Jacobs escribió:
Dear Fermin and all,

Thank you very much for this initiative! From NEC side we support to update the API based on the real-life experience.

I think we first have to discuss about the format of the specification. I do not mind having the specification in some interactive online format; this is actually something positive.

However, while the way the API is currently represented on http://telefonicaid.github.io/fiware-orion/api/v2 is certainly extremely useful for users who want to quickly find out how to do certain things, it is not systematic enough and developers will have a hard time to implement the full API using this “specification by use cases”, and it will be hard to check it for consistency, completeness, etc.


-          What is most urgently needed is a complete description of the resource tree, for each operation on each resource explaining the request message body, the URL parameters, the response body, and the effect of the operation.


-          Then probably a description of the data model and its JSON representation is required as well, especially if there are updates in the new API version.

[FGM1] We are in a process of refactoring that first draft (first PR on the way: https://github.com/telefonicaid/fiware-orion/pull/1006) into two apiary documents: one to focus on examples (similar approach to the one used by the current draft at the URL) and one to provide the API reference (I understand that adressing the point you mention). I encorage you (and any other! :) to provide feedback in PR comments as we go working on the documents.

To start discussing about the API itself, let me first ask some basic questions:


-          Do you intend to keep the distinction between NGSI 9 and NGSI 10? In my view it would be useful to at least sharply distinguish between operations for exchanging information and operations for exchanging “availability information”.

[FGM2] That difference could be explained in the introductory sections, before depicting each operation. What we have found is that people find confusion "NGIS9" and "NGSI10" (they tend to confuse with version 9 and version 10 of a thing called "NGSI"), so probably we should discuss about "context" and "context availability" but without mentioning NGSI9 and NGSI10.


-          I think it would be good to keep the approach of having a set of basic operations (queryContextRequest etc.) with which in principle one can do everything, so that convenience operations only add convenience but not add functionality as compared to the basic operations?

[FGM2] In general, I agree. In fact, we plan to include standards operations also as part of the reference documentation. As I mention in my previous email: "The current draft at the above URL is focused on not-standard operations (sometime referred as "convenience operations") but at the end it will also include a specification for the standard operations (e.g. queryContext, updateContext, registerContext, etc.) based in the one we already have for the JSON encoding of that operations in the v1 API". However, there are some exceptions, eg: the convenience operation to get all the entity types ("GET /v2/types") in the sytesm doesn't have any counterpart in the standards operation family. But I understand that this is not a mayor problem.

Best regards
Tobias



From: fiware-ngsi-bounces at lists.fi-ware.org<mailto:fiware-ngsi-bounces at lists.fi-ware.org> [mailto:fiware-ngsi-bounces at lists.fi-ware.org] On Behalf Of Fermín Galán Márquez
Sent: Freitag, 12. Juni 2015 12:28
To: fiware-ngsi at lists.fi-ware.eu<mailto:fiware-ngsi at lists.fi-ware.eu>
Subject: [Fiware-ngsi] FIWARE NGSI API v2

Hi,

After 17 months since we released FIWARE NGSI bindging API v1.0 at http://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_NGSI:_publicly_available_documents and taking into account the large experience looking to how developers are using the API and the feedback that they have provided directly in many events (Campus Parties, Startup Weekends, Developers Weeks, etc.) or using other supporting channels (StackOverflow, mailing list, direct email, etc.) we think we are in the right moment to release a new major version of the binding (named v2.0).

The main design principle in the new version should be simplicity and ease of use for developers. This is for us the absolute priority in the API design if we want to get wide adoption. We want an API so simple to use but powerful at the same time that developers "fall in love" with it. For example, we have found that developers find too verbose the v1.0 convenience operations API and we should fix that. Developers also complaint about that v1.0 is not actually RESTful (e.g. HTTP response codes are not used to encode the result of the operation).

You can find a draft of the v2.0 API at http://telefonicaid.github.io/fiware-orion/api/v2. Apart from the Apiary documentation, some of the operations have a textual specification with more detail, published as github.com issues (the index for reaching the textual specification from the operation type is at https://docs.google.com/spreadsheets/d/1f4m624nmO3jRjNalGE11lFLQixnfCENMV6dc54wUCCg/edit#gid=50130961 tab "NGSI API v2 operations"). At the end, this textual specification would be probably merged into Apiary to have all the information in the same place.

Some of the main characteristics (all them in the aforementioned line of simplicity and ease of use):

  *   Fully based on JSON. Nobody uses XML in modern REST APIs nowadays.
  *   Fully-fledged query language in URL params for GET operations
  *   To flatten information as much as possible, e.g. attribute fields are at the very same level in the JSON than entity id/type
  *   Using HTTP response code for error managing instead that in-payload information
  *   RESTFul API aligned with the latest industry trends
The current draft at the above URL is focused on not-standard operations (sometime referred as "convenience operations") but at the end it will also include a specification for the standard operations (e.g. queryContext, updateContext, registerContext, etc.) based in the one we already have for the JSON encoding of that operations in the v1 API.

Thus, the plan is as follows:

  *   Get feedback and agree in a final version of the API.
  *   Start promoting the new NGSI API v2 in FIWARE events (e.g. Developers week, hackathons, etc.)
  *   Prepare the "outputs" corresponding to the API specification, i.e. the "equivalent" of the v1 .zip for v2. It is obsolete nowadays to release a REST API as a set of PDF files along with an XSD file. Thus, for v2 what we propose is to use an Apiary blueprint as basic specification, along with other resource files that may be necessary/useful (such as JSON Schemas, RAML, etc.). We are currently researching on this, so any feedback in this topic is specially welcome.
  *   Implement v2 in NGSI-compliant FIWARE components. From the point of view of Orion Context Broker, our plan is to have most of the v2 API implemented by September 2015.
Last but not least, let me introduce to Jose Manuel Cantera, who is the main designer of this proposal and will be working on this topic within the TID team.

Your feedback is very welcome and necessary! Thanks for your contributions and support!

Best regard,

------
Fermín
Thanks for the feedback!

Best regards,

------
Fermín

________________________________

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/20150616/93a3f8e0/attachment.html>