[Fiware-ngsi] FIWARE NGSI API discussion points

[Tobias Jacobs]

Dear Fermin and all,

The NGSI v2 proposal is very rich and there will be many different things to discuss or clarify. I am not sure what is the best "format" for the discussion, but let me start in this email with a few points (most of them questions). We are not done yet analyzing the complete proposal and more discussions will follow.

I refer to the current version of

http://telefonicaid.github.io/fiware-orion/api/v2/

Best regards
Tobias


1)      "flat" JSON message:
In general NEC agrees to reserve "id", "type", "value" to have special semantics. Even if this means that entities can have no attributes called "id", "type" or "value"

Alternatively (and for maybe making the descriptions easier to understand) we might think about calling "id", "type", "value" special attributes with special semantics; some being mandatory (e.g. "id" is mandatory in entities).


2)      Predefined value types: in general NEC supports to have predefined types in order to improve interoperability


3)      JSON types as predefined value types: We understand that a JSON property whose value is not a JSON object (and thus has no explicitly stated type) is implicitly either of type "number", "string" or "boolean", depending on the type of the JSON property. So for example "temperature": 32.5 would be implicitly of type "number".



4)      Further predefined value types: We also understand that there will be further predefined types like for example "geo:point".  But we believe that attribute values having this kind of type will still need to be a JSON object with explicitly stated "type" property, because otherwise e.g. one cannot distinguish a "date" value from a "string" value. This would mean that the example "timestamp": "2017-06-17T07:21:24.238Z" is incorrect and would instead have to look like

"timestamp":{
               "value": "2017-06-17T07:21:24.238Z"
              "type": date
}



5)      Further predefined value types: We assume that some predefined value types can refer to specific JSON object formats, not only to specific string formats.


6)      User-defined types: It is currently written that "The values of user-defined informative types are represented by JSON string", but we believe that user-defined types should be representable by numbers, Booleans and JSON objects as well.


7)      Error format: Currently an error code is not specified. Is this because it is intended to use the status code in the HTTP header instead? Can this lead to conflicts between standard HTTP error codes (e.g. 404 resource not found) and NGSI error codes (eg. 404 context element not found)?


8)      API entry point
In general NEC agrees to make this resource somehow an overview of the main API urls. Would you make the format if this link list predefined, or would you leave the specific format to the API developer?


9)      Pagination: In principle NEC supports the concept of pagination. However we are not sure how it can be realized in practice, as query results are dynamic (especially when getting the queried data live from a distributed system like IoT systems do). What the user probably expects is that the query results are "frozen" for him and then delivered page by page. But then something like a query ID is needed to collect the query results.
Alternatively the query result could be represented by a specific http resource (which is similar to a query id).
In both cases things become slightly more complex...

Do you have a proposal how to deal with that issue?







-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.fiware.org/private/fiware-ngsi/attachments/20150629/9e7f5efa/attachment.html>