Re: [controller-dev] REST-API deviation in convention (Subject renamed)

Madhu Venugopal

Expanding the invite to all the dev aliases.

Based on the discussion on this email thread and over IRC, we are calling for a 1+ hr webex meeting
tomorrow (11/07/2013 @ 12pm PST).
Webex details @
or via the events page :

Please participate and provide your inputs.


On 11/5/13, 7:13 AM, Madhu Venguopal wrote:
Hi Alissa, Prasanth,

As we all agree, REST-API definitions are more of recommendations and conventions that are widely used.
And the definitions for PUT, POST are a bit vague. Having said that, it is better to follow a convention that
is widely accepted norm. It will be a disaster if each of the projects decide to go with its own convention.
Rather there MUST be a standardized approach.

With REST-CONF development also underway, we need to find that consensus and fast.

IMHO, The API freeze deadline that was set in the past didnt workout as expected.
Since we are NOT discussing about functionality changes and merely the best practice / convention on defining
the REST-API, I would recommend to take inputs from the community and other experts who had dealt with REST-API
definitions in the past.

Again, it is highly recommended to follow a well-known convention (AWS, OpenStack, etc...) and stick to it.

Since the TWS call for this week was cancelled, either we can take it up in the next week call
(or) I can call one this week and hope most of the experts and stake-holders can make it.

So, far we have just heard from 4-5 of us on this topic (and I hope the inclusion of discuss alias and subject change will help).


On 11/5/13, 12:37 AM, Alissa Bonas wrote:

----- Original Message -----
From: "Prasanth Pallamreddy (ppallamr)" <ppallamr@...>
To: "Alissa Bonas" <abonas@...>
Cc: "Madhu Venugopal" <mavenugo@...>, "Ryan Moats" <rmoats@...>, "Giovanni Meo (gmeo)" <gmeo@...>,
"Anees A Shaikh" <aashaikh@...>, "controller-dev" <controller-dev@...>, "Nikhileshkumar
Ikhar" <nikhil.ikhar@...>
Sent: Tuesday, November 5, 2013 5:48:30 AM
Subject: Re: [controller-dev] Unable to add user with command line

See inline ... [PP]

On 11/4/13 12:21 PM, "Alissa Bonas" <abonas@...> wrote:


I am still failing to understand why PUT is better for creating new
Based on the amazon web practices that you enclosed, it states that most
of the cases use POST when creating new entities.

And looking at the http spec, it also states that POST is used to create
new entities as well:

Please also see this article on REST api design:

Using PUT for creating new entities does not provide a clear separation
for user which will have to use it for both creation and update. It is
very misleading for clients to use same api for 2 different purposes.
[PP] As I said earlier, the issue is grasping whether an update operation
is idempotent or not. Not all update operations are idempotent in which
case you'd have an overloaded POST to handle both create and update
operations. So, the same question and confusion remains. Again, I am not
talking just about the user manager API, but rather all the APIs that have
been exposed in ODL. Also, not all APIs adhere to the 'PUT for create'
recommendation. If you look at FlowProgrammer NB, you'd see that the PUT
method has been overloaded to handle both creates and updates since the
POST has been reserved for some other operation.

Moreover, it is not recommended for clients to define their own urls on
server, or in other words to use non existing urls as in case when using
PUT for creation. Why the clients should use non existing urls or have
assumptions about it? All client wants is to add a new entity to an
existing collection (user/host/switch/etc.), and he should not interfere
with server's work to do so, he needs to supply the details of what
should be created and that's it. And consider this case - the resource
identifier may be (and in most cases it is) an id that server generates,
not a name that client sends. How in this case the client will create the
url of something that doesn't exist yet and is up to server to generate?
[PP] The current APIs that we expose, in almost all the cases, the
resource path is known. The server can reject the request if the requested
resource path doesn't comply. In some of the APIs there is redundant
resource information (in the path and the request payload) and the server
rejects it if there is a mismatch. Also, this isn't a hard rule. So, for
cases where the path is server generated, POST can be used. I wouldn't
admit that the APIs are perfect. Since we are in API freeze currently, the
issues can be addressed in v3.
What is the timeline for v3?

Join to automatically receive all group messages.