[Fiware-ngsi] proposed expansion of NGSI-10

[Bisztray, Denes (NSN - HU/Budapest)]

Hi Tobias,

 

I checked the OMA Spec for RESTful APIs (both that was sent by Lorant), and we have the following:

 

-          POST is for

o   Creation of a subordinate resource addressed at the parent resource (i.e. creation of a ContextElement posted to the /contextElements) - (Sec 5/2.c and Sec 5.5) 

o   Partial update of a resource (Sec 5/2.c)

o   Partial update of one or more subordinate resources (Sec 5/2.c)

-          PUT is for

o   If points to an existing resource, it does a complete update, which is idempotent.

o   If points to a nonexistent resource, it creates it.

 

This translates to the following:

 

-          UpdateContextInformation at /contextElements remains a POST

-          New subscription creation at /subscriptions remains a POST

-          UpdateSubscription at /{subscriptionId} can be both POST and PUT depending on the update: if its complete rewrite it is a PUT, if a partial it is a POST.

-          Creation of a Context Element at /{contextElementId} is a PUT

-          Updating a Context Element at /{contextElementId} can be both POST and PUT with the similar reasoning, i.e. complete rewrite vs partial update

 

However we have a little problem here. 

 

At the partial update POST at subordinate resource (i.e. /{contextElementId}) the mandatory fields of the involved data structures are still mandatory, and as such they have to be included. So I wonder how can we have a partial update when we have to send possibly all information again, like in a complete rewrite...

 

What do you think of this?

 

Best,

Dénes 

 

 

 

From: ext Tobias Jacobs [mailto:Tobias.Jacobs at neclab.eu] 
Sent: Wednesday, February 08, 2012 1:57 PM
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/e8f824ba/attachment.html>