[Fiware-ngsi] Comments on the NGSI-9 and NGSI-10 REST binding drafts

[Ken Zangelin]

Hi there,

I'm Ken Zangelin, the software engineer at Telefonica I+D that is to implement the 'Things and Resources Management GE'.
I was recently incorporated in FI-WARE IoT, but I'm in the Data 'chapter' (Samson) since last summer.
I'm sure some of you have already seen me either in Torino or in Madrid.

So, I've been reading the docs about NGSI-9/10 REST.
I'm pretty new to all this and I have had a bunch of documents to read through in very little time,
so don't be too surprised if some of my doubts don't make too much sense and are clearly explained elsewhere ...
I just haven't had time enough ...
Also, when I start to implement this, I'm afraid many more questions will arise ... :-)

Now, it would be good if a developer could read these documents and have a completely clear picture on what he/she needs to implement.
I mean, down to the last byte in the implementation.
One way to accomplish this is to include examples, perhaps using curl commands, on all requests that are to be supported and responses
that are to be produced. It would also be good to show examples of exact input data for each REST request and a few examples of 'exact'
output data to be produced. HTTP headers, etc. The works!
Most of this information is found in other documents and clear references to those docs would be in place, wherever needed.

Personally, I would have preferred to have all the information gathered in one single document.
But that's just a matter of taste.

Another very useful thing would be to have a sample ContextProvider/ContextConsumer implemented, to use during tests.
Is there anything like that? I mean, a running executable.
Either as running services, visible on the internet, or downloadable source code to compile and install locally.

Also, being able to connect to the IoT-Broker and Pub/Sub Broker would be very valuable during the implementation/testing phase.
Perhaps we could mount a 'test' IoT-Broker and Pub/Sub Broker ... ?
Detailed information on IP addresses, port numbers, etc., or just a reference to another document that addresses this ...


OK, here are my comments so far on the NSGI-9/10 RESTful binding docs:



Comments on 'NGSI-10 RESTful binding':
--------------------------------------------------------
o 1.1
   o Data structures in XML
   - is JSON not to be supported?

o 1.2.1
   o An EntityId contains an Id-String and a Type
   - Details on how this is coded in the REST request {EntityID} in the convenience functions ...
     A software engineer will parse this input and if it is not stated exactly how the Id-String and Type inside the EntityId are
     represented ... What is the delimiter?
     Or have I misunderstood this? Is {EntityID} only the Id-String in the REST request path of the convenience operations?
     If so, please make sure the reader understands that.

o 1.2.2
   o Metadata
   - How is the metadata sent?
   - This becomes clear in the xml examples, but some more detail would be nice here ...

o 2 (path image)
   o From this image, you get the impression that an 'EntityID' cannot contain the character '/'.
   - Is this so?
   - It might be useful to be able 'group' EntityIDs using the '/':   'myhome/livingroom/tvcorner' ...

o 2.1.2
   o Typo: 'tyeName'
   o Possible cut n' paste error:
     'Context entity type' and 'Attribute container of entity type' has the exact same description ...

o 2.1.3
   o URI parameters for 'scope'
   - What are the 'scope types' and their possible values?
     - A few examples would be nice

o 2.2
   o notifyContextRequest / notifyContextResponse
   - notifyContextRequest.xml and notifyContextResponse.xml seem to be missing in 'trunk/schemes/xml_examples/ngsi-10/' ...

o 3.1.2
   o ContextMetadata, ContextAttribute, ContextAttributeResponse, ContextResponse - hints on where to find details
     Reference to the schema file ...




Comments on 'NGSI-9 RESTful binding':
--------------------------------------------------------

First, on 'availability'. I haven't been able to find any description on what exactly is meant with 'availability'
so I've assumed that the fact that an Entity/Attribute exists, means it is available.
Actually I had expected to find some boolean value or a 'time frame' or something to define the availability ...
The only thing I've found that is related is the 'duration', in 'registerContextRequest.xml'.
It would have been good (at least for me) to have this explained in the document - the exact measning of 'availability'.


2.1.1
     o registerContext
       From what I've read in the docs, the 'registerContext' should allow registering and updating Context Entities, with attributes
       and availability, but it should not handle the attribute values.
       - Now, 'trunk/schemes/xml_examples/ngsi-9/registerContextRequest.xml' seems to include values of the attributes ...

       Also, the '<duration>PT1M</duration>' part at the end if 'registerContextRequest', perhaps a reference to the definition
       of this way to measure duration (http://en.wikipedia.org/wiki/ISO_8601) ...

       Another question: can attributes be removed from an Entity?

     o discoverContextAvailability
       Here you just got the name of the XML example files wrong, they're called 'discoveryContextAvailabilityRe*.xml', using
       the word 'discovery' instead of 'discover' ...
       - I was hoping to find some information on 'scopeType' here in this example ...
       Please add a description of the meaning of scope in detail in the doc.

     o subscribeContextAvailability
       Does really the 'subscriber' decide the subscriptionId in the subscribeContextAvailabilityRequest?
       I know too little about this, but it seems a little strange that the 'client' fixes the id of a subscription ...
       To me it would be more logical for the Response to contain the id, defined by the 'server' ...

     Is there no way to ask for a list of all the existing Entities?
     I mean, if you don't know the EntityId, there is not much you can do ... ?
     Ah wait, we have the convenience function that works on Type Names ...

     What about Type Names ... ?
     Are we supposed to accept any string or are the valid Type Names predefined somewhere?
     What characters are valid in a type name?
     Also, do we have any naming conventions ... ?
     Not only for type names, but also entity ids, attrribute names, etc. I've always liked the 'uppercase and not underscore' approach.

OK, that's all for now.

Regards,

/KZ


________________________________

Este mensaje se dirige exclusivamente a su destinatario. Puede consultar nuestra política de envío y recepción de correo electrónico en el enlace situado más abajo.
This message is intended exclusively for its addressee. We only send and receive email on the basis of the terms set out at.
http://www.tid.es/ES/PAGINAS/disclaimer.aspx