[Fiware-ngsi] NGSI-10 RESTful binding draft

[Tobias Jacobs]

Hi Laurent and Laurence, all,

Thanks a lot for your detailed comments. I will update the document based on your comments as soon as possible.
Please find my answers inline.

Thank you also for providing the NGSI9/10 class diagram. I am not sure where there is a place in the wiki where it is accessible to the members of this mailing list.

Best
Tobias


From: laurent.artusio at orange.com [mailto:laurent.artusio at orange.com]
Sent: Montag, 16. Januar 2012 15:37
To: Tobias Jacobs
Cc: fiware-ngsi at lists.fi-ware.eu
Subject: RE: [Fiware-ngsi] NGSI-10 RESTful binding draft

Dear Tobias,

We understand that your REST binding contains modifications and extensions to the actual NGSI-10 specification.
We actually did not intend to modify or extend the NGSI functionality. If we did so, then it was by mistake.

Here are our comments and understanding for every row of the 2.1.1 table related to every paragraph of your document:

2.2 Context element container
We understand this method as being like updateContext, but instead of providing an array of full ContextElement structures, a single entityId structure that belongs to a ContextElement is provided and used as the key.
I Agree.

First, it seems the "Base URL" column lacks the needed /{contextElementID}.
The mistake I made is that \{contextElementId} needs to be removed from the url in Section 2.2.


Secondly, the "context element container" is a resource update, which means the PUT method would be more adapted in a REST style interface. But we think you've chosen the POST method because it certainly allows to return a payload, which is needed by the updateContext NGSI method (it is supposed to return an array of ContextElementResponse).
Yes, and another reason is that PUT should be idempotent, but the updateContext operation is in general not idempotent (e.g. when using updateActionType "append").

2.3 Individual context element
Looks equivalent to the queryContext method without restriction, with a single entityId and without attributeList. This returns everything for a particular contextElementId. We don't understand what is meant by contextElementId: is it the id field of the EntityId data structure ? Because we don't know if it's possible for HTTP GET to carry XML payload. Therefore the id has to be a simple string if no XML payload is allowed in GET(but we're not sure)
Yes, the id field of the EntityId data structure (which is a xs:string indeed) determines the last part of the resource address. I should make this more clear in the document.

2.4 Attribute of individual context element
Looks equivalent to the queryContext method without restriction, with a single entityId and with a single attribute in the attributeList array. Therefore, shouldn't  the response be a single ContextElementResponse instead of the suggested QueryContextResponse ?
This question is the same 2.3 I think. We propose to return a QueryContextResponse for consistency reasons, and also because QueryContextResponse contains an additional field for general operation errors.

2.5 Attribute domain of individual context element
Can be considered as a brand new method, as it is capable of returning all attributes of a specific domain. It does not look possible to do that in actual NGSI-10. We think it is a good feature.
To my understanding it corresponds to  NGSI operation queryContext with a single entityId and with a single attribute in the attributeList array, where "isDomain" of the attribute is "true".

2.6, 2.7, 2.8 Type related features
Looks like new features. Have no equivalent in actual NGSI-10. We don't exactly understand what a type is. Is it the "type" field of EntityId data structure ?
Yes, it is the "type" field of EntityId. We believe that it is convenient to access all elements of a certain type, like "all rooms", or "the temperature of all rooms".  As there could be millions of entities having the same type in a large system, we proposed the possibility to define a scope in the request URL (table in 2.6.1).
A GET on a <context element type> resource corresponds to a queryContext with a single entityID having "isPattern=true", "id=*" and e.g. "type=room", and without attribute list, so again it is just a convenience function instead of really new functionality.

2.9 Context query resource
We understand it as an exact http mapping of the queryContext method, the HTTP POST payload containing the input parameters, and the HTTP POST response containing the optional output ContextElementResponse array.
I agree.

2.10 Subscription container
Same as above: we understand it as an exact http mapping of the subscribeContext method.
Same as above: I agree.


2.11 Subscription
Depending on the HTTP verb: modify a subscribing if the HTTP PUT verb is used, or delete a subscribing if the HTTP DELETE verb is used. These are respectively equivalent to the updateContextSubscription method and unsubscribeContext method.

But does the HTTP protocol allow the PUT and DELETE method to carry a response payload as described in your document ?
I am afraid that you are right and we have to use POST for both updateContextSubscription and unsubscribeContext. We could think about allowing also the PUT and DELETE verbs, for cases when the user is satisfied with the simple HTTP response header.

2.12 Notification
We understand it as an exact http mapping of the notifyContext method.
I agree.


Conclusion:
We are aware of the difficulty of making a REST mapping for NGSI, since NGSI it is not natively related to a resource oriented architectural style. NGSI is a classical API with its methods. Therefore it is likely it won't be really possible to convert it into "real REST". It is disappointing because a REST-styled architecture really fits the need of the internet of things, with possibly tree-like representations of "things" mapped to HTTP URIs.
I agree. The main obstacle seems to be the fact that NGSI admits pretty complex operations. We tried to design the binding so that at least a subset of the functionality can be realized in a RESTful way.

We provide an attached NGSI-9-10 class diagram, for any useful purpose. Feel free to tell us a good place to paste it in the wiki.

Best regards,

Laurent and Laurence

De : fiware-ngsi-bounces at lists.fi-ware.eu<mailto:fiware-ngsi-bounces at lists.fi-ware.eu> [mailto:fiware-ngsi-bounces at lists.fi-ware.eu]<mailto:[mailto:fiware-ngsi-bounces at lists.fi-ware.eu]> De la part de Tobias Jacobs
Envoyé : vendredi 13 janvier 2012 09:08
À : fiware-ngsi at lists.fi-ware.eu<mailto:fiware-ngsi at lists.fi-ware.eu>
Objet : [Fiware-ngsi] NGSI-10 RESTful binding draft

Dear members of the OMA NGSI mailing list of FI-WARE,

In the end of last year NEC has created a draft version for a RESTful NGSI-10 binding specification which I would like to present here, please see docfile in the attachment.

I am looking forward to receive comments/questions on this.

Best regards
Tobias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.fiware.org/private/fiware-ngsi/attachments/20120116/6b453516/attachment.html>