POST vs PUT in v0 HTTP endpoints

[Benjamin Mahler <bm...@apache.org>]

I noticed that we have some inconsistent usage of POST vs PUT (only 1
endpoint uses PUT today), so I did a little survey of our endpoints:

https://docs.google.com/document/d/1yo-ZcKAdrCwBmTDkAKGNLnhK7fAfwatKddZrhtpgyMk/edit?usp=sharing

A couple of findings:

* We often don't look at the method, so most GET endpoints will work the
same when sent a POST, PUT, etc. Presumably, we can fix this without
breaking users.
* Most writes are done with POST, regardless of whether the writes are
idempotent.
* Only /master/weights uses PUT (no POST) for its idempotent writes.

After discussing with Anand and Vinod, we felt it would be easiest for
users if all writes are done with POST. As part of this we would update
/master/weights to use POST to make it consistent. Let me know if there's
any feedback on this!

Ben

Re: POST vs PUT in v0 HTTP endpoints

[Benjamin Mahler <bm...@apache.org>]

I can appreciate the desire to clarify idempotency for users explicitly in
the API, but I'm not sure that we'll be able to do this so easily. For
example, it seems to me there are many existing POST API calls that are
actually idempotent, I can tell mesos to teardown the framework multiple
times, and that shouldn't change the result: the framework is torn down.
However, it seems a little strange from a user perspective to teardown a
framework via a PUT, or is it just me?

That is indeed a related question :)

On Wed, Aug 2, 2017 at 9:28 AM, Zhitao Li <zh...@gmail.com> wrote:

> As one of the developers who considered PUT, I actually feel that being
> able to distinguish idempotent API calls with a PUT method at
> least provides more self-explanatory semantic.
>
> Another thing to consider is whether certain SDK which can generate client
> libraries from REST API prefers PUT for idempotent operations.
> Unfortunately I'm not experienced in this area so I don't have answer for
> that, nor do I know anybody doing such things.
>
> A related question: do we have a clear timetable of deprecating V0
> endpoints (or at least stop maintaining feature parity with V1 API)?
>
> On Tue, Aug 1, 2017 at 3:55 PM, Benjamin Mahler <bm...@apache.org>
> wrote:
>
> > I noticed that we have some inconsistent usage of POST vs PUT (only 1
> > endpoint uses PUT today), so I did a little survey of our endpoints:
> >
> > https://docs.google.com/document/d/1yo-ZcKAdrCwBmTDkAKGNLnhK7fAfwatKd
> > dZrhtpgyMk/edit?usp=sharing
> >
> > A couple of findings:
> >
> > * We often don't look at the method, so most GET endpoints will work the
> > same when sent a POST, PUT, etc. Presumably, we can fix this without
> > breaking users.
> > * Most writes are done with POST, regardless of whether the writes are
> > idempotent.
> > * Only /master/weights uses PUT (no POST) for its idempotent writes.
> >
> > After discussing with Anand and Vinod, we felt it would be easiest for
> > users if all writes are done with POST. As part of this we would update
> > /master/weights to use POST to make it consistent. Let me know if there's
> > any feedback on this!
> >
> > Ben
> >
>
>
>
> --
> Cheers,
>
> Zhitao Li
>

Re: POST vs PUT in v0 HTTP endpoints

[Zhitao Li <zh...@gmail.com>]

As one of the developers who considered PUT, I actually feel that being
able to distinguish idempotent API calls with a PUT method at
least provides more self-explanatory semantic.

Another thing to consider is whether certain SDK which can generate client
libraries from REST API prefers PUT for idempotent operations.
Unfortunately I'm not experienced in this area so I don't have answer for
that, nor do I know anybody doing such things.

A related question: do we have a clear timetable of deprecating V0
endpoints (or at least stop maintaining feature parity with V1 API)?

On Tue, Aug 1, 2017 at 3:55 PM, Benjamin Mahler <bm...@apache.org> wrote:

> I noticed that we have some inconsistent usage of POST vs PUT (only 1
> endpoint uses PUT today), so I did a little survey of our endpoints:
>
> https://docs.google.com/document/d/1yo-ZcKAdrCwBmTDkAKGNLnhK7fAfwatKd
> dZrhtpgyMk/edit?usp=sharing
>
> A couple of findings:
>
> * We often don't look at the method, so most GET endpoints will work the
> same when sent a POST, PUT, etc. Presumably, we can fix this without
> breaking users.
> * Most writes are done with POST, regardless of whether the writes are
> idempotent.
> * Only /master/weights uses PUT (no POST) for its idempotent writes.
>
> After discussing with Anand and Vinod, we felt it would be easiest for
> users if all writes are done with POST. As part of this we would update
> /master/weights to use POST to make it consistent. Let me know if there's
> any feedback on this!
>
> Ben
>



-- 
Cheers,

Zhitao Li