[Fiware-ngsi] proposed expansion of NGSI-10

[Farkas, Lorant (NSN - HU/Budapest)]

Dear All,

 

I apologize, I wanted to send this doc, not the earlier one.

 

Br,

 

Lorant

 

From: ext Tobias Jacobs [mailto:Tobias.Jacobs at neclab.eu] 
Sent: Wednesday, February 08, 2012 6:26 PM
To: Farkas, Lorant (NSN - HU/Budapest)
Subject: RE: [Fiware-ngsi] proposed expansion of NGSI-10

 

Hi all,

 

I did not find a clear answer in the OMA conventions, but we could try to find similar examples in other OMA RESTful bindings.
The blog post link provided by Stefan is more in favor of POST. 

What in my opinion speaks for PUT is that the UpdateSubscription operation fulfills both requirements of PUT: idempotency and freedom of side-effects. 

 

About Stefan's other points:

 

1.       Why aren't there any GET operations to retrieve the list of ContextElements as well as a list of subscriptions and individual subscriptions?

 

Such operations are thinkable and probably pretty useful. Only there is no corresponding functionality defined in the NGSI specs - I am not sure if this is a problem or not.

 

2.       When updating a subscription, the URI already identifies the subscription. Why do we still need the subscription ID in the message body?

 

I see no reason that the ID must be in the message body. Maybe consistency to the NGSI specs would be a reason, but then the server also would need to check if the uri and the subscription id in the body are the same.




3.       Failing operations (e.g., GET /contextElements/room1 when there is no context element "room1") will have a response code 200 (OK), with the error listed in the status code field of the response message. Not very nice, as if always necessitates to parse the response message.

 

I agree, that should indeed be avoided.

 

Best regards

Tobias

 

 

From: Farkas, Lorant (NSN - HU/Budapest) [mailto:lorant.farkas at nsn.com] 
Sent: Mittwoch, 8. Februar 2012 15:00
To: ext Haller, Stephan; Tobias Jacobs; Bisztray, Denes (NSN - HU/Budapest); fiware-ngsi at lists.fi-ware.eu
Subject: RE: [Fiware-ngsi] proposed expansion of NGSI-10

 

Dear All,

 

I took my arguments from the book "RESTful Web Services" from Oreilly that extensively quotes the author of the RESTful PhD dissertation (I forgot his name).

Suggestion: what if we followed guidelines from other OMA specs? For instance we could use the conventions from OMA ParlayREST, see attached.

 

Br,

 

Lorant

 

From: ext Haller, Stephan [mailto:stephan.haller at sap.com] 
Sent: Wednesday, February 08, 2012 2:47 PM
To: Tobias Jacobs; Farkas, Lorant (NSN - HU/Budapest); Bisztray, Denes (NSN - HU/Budapest); fiware-ngsi at lists.fi-ware.eu
Subject: RE: [Fiware-ngsi] proposed expansion of NGSI-10

 

All,

 

An excellent blog about the PUT/POST problematic is also available at http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-rest-of-the-story/.

 

Some additional questions that my colleagues brought up (Armin, Fabian, please feel free to add!):

1.       Why aren't there any GET operations to retrieve the list of ContextElements as well as a list of subscriptions and individual subscriptions?

2.       When updating a subscription, the URI already identifies the subscription. Why do we still need the subscription ID in the message body?

3.       Failing operations (e.g., GET /contextElements/room1 when there is no context element "room1") will have a response code 200 (OK), with the error listed in the status code field of the response message. Not very nice, as if always necessitates to parse the response message.

 

Regards,

-Stephan

 

 

From: fiware-ngsi-bounces at lists.fi-ware.eu [mailto:fiware-ngsi-bounces at lists.fi-ware.eu] On Behalf Of Tobias Jacobs
Sent: Mittwoch, 8. Februar 2012 13:57
To: Farkas, Lorant (NSN - HU/Budapest); Bisztray, Denes (NSN - HU/Budapest); fiware-ngsi at lists.fi-ware.eu
Subject: Re: [Fiware-ngsi] proposed expansion of NGSI-10

 

Hi Lorant,

 

Thanks for your fast reply.

Up to now I had assumed that PUT is used for changing an existing resource (not matter if it is a complete renewal or a partial change) and POST is used for creating new resources. 

 

Some random links about the question:
http://www.ibm.com/developerworks/webservices/library/ws-restful/ 

http://en.wikipedia.org/wiki/Representational_state_transfer 
(here PUT is used for replacing resources like you state it, but POST is only used for adding something. It is not mentioned how to change one aspect of a resource)

 

http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html 

Also kind of supports both views...

 

My feeling is that it is nowhere clearly written which operation to use for changing one aspect of a resource...

 

The request need not be idempotent: if you POST twice that the NotifyCondition is now OnSomething and OnSomethingElse and earlier it was just OnSomething, it doesn't matter how many times you POST it (it would only be a problem if you had fields like NumValue and you would have NumValue++ in the POST).

 

This property of UpdateSubscription is exactly what understand under idempotency: If you apply the same operation n times in a row, the result will be the same as when applying the operation only once. And the usage of the verb PUT gives a hint that subscription updates are in fact idempotent, because PUT is required to be idempotent (while POST does not need to be in general).

 

Best

Tobias

 

From: Farkas, Lorant (NSN - HU/Budapest) [mailto:lorant.farkas at nsn.com] 
Sent: Mittwoch, 8. Februar 2012 13:22
To: Tobias Jacobs; Bisztray, Denes (NSN - HU/Budapest); fiware-ngsi at lists.fi-ware.eu
Subject: RE: [Fiware-ngsi] proposed expansion of NGSI-10

 

Hi Tobias,

 

Why would you prefer POST over PUT for subscription updates? From my point of view, PUT the natural verb to do this. Subscription updates are also idempotent, as expected from PUT.

 

My understanding of REST is that whenever you change something in an existing resource - at an existing endpoint, you use POST. For instance, if you modify the NotifyCondition only, for an existing resource, then you update the resource but do not replace it. That is POST. This is equivalent to setting your status from away to online in Facebook: the resource is the same, but some of the content changes.

The only difference is if you replace the whole resource but the URL of the resource remains the same, then you could use PUT instead of POST. Like you create a brand new subscription under the same resource endpoint (in other words, the client has the control of the URL) that exists already, then you use PUT. 

The other case when PUT should be used is when you create a new resource and the client needs control of the URL (resource endpoint does not exist yet in the server).

 

The request need not be idempotent: if you POST twice that the NotifyCondition is now OnSomething and OnSomethingElse and earlier it was just OnSomething, it doesn't matter how many times you POST it (it would only be a problem if you had fields like NumValue and you would have NumValue++ in the POST).

 

Thanks & Br,

 

Lorant

 

From: fiware-ngsi-bounces at lists.fi-ware.eu [mailto:fiware-ngsi-bounces at lists.fi-ware.eu] On Behalf Of ext Tobias Jacobs
Sent: Wednesday, February 08, 2012 10:39 AM
To: Bisztray, Denes (NSN - HU/Budapest); fiware-ngsi at lists.fi-ware.eu
Subject: Re: [Fiware-ngsi] proposed expansion of NGSI-10

 

Hi Denes,

 

Thanks a lot for your propositions.

 

We have also discussed adding convenience functions for the put-operation a couple of days ago. 

One question is if the update message should really be a ContextElement (of ContextAttribute), or rather a full UpdateContextRequest, which also contains information on the updateActionType. One possibility would be to define a default updateActionType and give the possibility to change it via a parameter in the URI.

 

Why would you prefer POST over PUT for subscription updates? From my point of view, PUT the natural verb to do this. Subscription updates are also idempotent, as expected from PUT.

 

Best

Tobias

 

From: fiware-ngsi-bounces at lists.fi-ware.eu [mailto:fiware-ngsi-bounces at lists.fi-ware.eu] On Behalf Of Bisztray, Denes (NSN - HU/Budapest)
Sent: Mittwoch, 8. Februar 2012 09:52
To: fiware-ngsi at lists.fi-ware.eu
Subject: [Fiware-ngsi] proposed expansion of NGSI-10

 

Dear all,

 I checked the RESTful binding proposal created by Tobias an Laurent. I completely understand that the NGSI-10 standard allows only a mass-update of the context entities via the updateContextRequest. 

  What I propose is simple addition of update operations on the individual context elements and attributes of context elements.

-       Add a POST method to the Individual Context Element (/contextElements/{contextElementID})

-       Add a POST method to the Attribute of individual context element (/contextElements/{contextElementID}/{attributeName})

The post operation message would include the UpdateAction and note a ContextElementList, but the updated ContextElement. In case of a ContextAttribute, the updated ContextAttribute.

Correspondingly the output message would contain the ErrorCode and one ContextElementResponse structure. 

This is an addition to the standard, and I think this would ease the context information update process. What is your opinion?

Irrelevant comment: I also agree that the subscription update should be a POST method instead of the current PUT.

Best,

Dénes

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.fiware.org/private/fiware-ngsi/attachments/20120209/d6a6a5b4/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: OMA-WP-Guidelines_for_REST_API_specifications-20100827-D.doc
Type: application/msword
Size: 204800 bytes
Desc: OMA-WP-Guidelines_for_REST_API_specifications-20100827-D.doc
URL: <https://lists.fiware.org/private/fiware-ngsi/attachments/20120209/d6a6a5b4/attachment.doc>