[Fiware-ngsi] proposed expansion of NGSI-10

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

Hi Tobias,

 

Here goes the doc. Apparently I mixed up, the Append is the PUT (since the Context Attribute or Element does not exists it creates new) and the Update is the POST.

 

I also uploaded this to the SVN. 

https://forge.fi-ware.eu/scmrepos/svn/iot/trunk/documents/Ngsi10-RestfulBinding-Draft.docx

 

Best,

Dénes

 

From: ext Tobias Jacobs [mailto:Tobias.Jacobs at neclab.eu] 
Sent: Thursday, February 09, 2012 2:02 PM
To: Bisztray, Denes (NSN - HU/Budapest); Farkas, Lorant (NSN - HU/Budapest); fiware-ngsi at lists.fi-ware.eu
Subject: RE: [Fiware-ngsi] proposed expansion of NGSI-10

 

Sounds like a good idea.

So I wait for you document and then update the binding with the other points discussed in the last couple of days.

 

Best

Tobias

 

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

 

Hi Tobias,

 

I figured out a solution to the POST/PUT question in case of /{contextElementId} (and possibly /{subscriptionId}) cases.

 

We omit the UpdateActionType element, and 

-          PUT is for UpdateActionType::Update

-          POST is for UpdateActionType::Append

 

I'm currently working on the document with the corresponding "new" input and output messages. I'll send it hopefully today.

 

Best,

Dénes

 

 

From: ext Tobias Jacobs [mailto:Tobias.Jacobs at neclab.eu] 
Sent: Thursday, February 09, 2012 1:52 PM
To: Bisztray, Denes (NSN - HU/Budapest); Farkas, Lorant (NSN - HU/Budapest); fiware-ngsi at lists.fi-ware.eu
Subject: RE: [Fiware-ngsi] proposed expansion of NGSI-10

 

Hi Denes, Lorant, all, 

thanks a lot for providing the information on REST verbs. Now I am more convinced to use POST for subscription updates.

 

 

-          UpdateContextInformation at /contextElements remains a POST

agreed.

-          New subscription creation at /subscriptions remains a POST

agreed.

-          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.

I would say it is always a POST, because the complete rewrite is only a very special case, and in general the operation is a partial update. 

-          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

In NGSI 10 there is no particular operation that creates a contextElement. You can simply use the updateContext operation to push attribute values into the context management component even if it is the first time the  context management component ever hears about a ContextElement with that ID. In other words, there is no distinction between creating and updating context information in NGSI 10 from the Context Provider Component point of view.
I would therefore recommend to only allow POST at /{contextElementId} and /{contextElementId}/attributeName.

 

 

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?

 

Which mandatory data structures do you mean? If the request body is an instance of ContextElement as discussed in a previous email (see below), then the only mandatory field is the EntityId (however the Id is already encoded in the access URI, so we might not require it in the body). Into this ContextElement one only puts the ContextAttributes and DomainMetadata which one wishes to update.

Best regards
Tobias

 

 

From: Bisztray, Denes (NSN - HU/Budapest) [mailto:denes.bisztray at nsn.com] 
Sent: Donnerstag, 9. Februar 2012 09:50
To: Tobias Jacobs; Farkas, Lorant (NSN - HU/Budapest); fiware-ngsi at lists.fi-ware.eu
Subject: RE: [Fiware-ngsi] proposed expansion of NGSI-10

 

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/84161b4a/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Ngsi10-RestfulBinding-Draft.docx
Type: application/octet-stream
Size: 64851 bytes
Desc: Ngsi10-RestfulBinding-Draft.docx
URL: <https://lists.fiware.org/private/fiware-ngsi/attachments/20120209/84161b4a/attachment.obj>