Hi,
On Sun, 2011-09-18 at 22:38 -0500, Jonathan Bryce wrote:
> After the mailing list discussion around APIs a few weeks back,
> several community members asked the Project Policy Board to come up
> with a position on APIs. The conclusion of the PPB was that each
> project's PTL will own the definition and implementation of the
> project's official API, and APIs across all OpenStack projects should
> follow a set of guidelines that the PPB will approve. This will allow
> the APIs to be tied to the functionality in the project while ensuring
> a level of consistency and familiarity across all projects for API
> consumers.
>
> We've started an Etherpad to collect input and comments on suggested
> guidelines. It's a little messy but proposed guidelines are set off
> with an asterisk (*):
>
> http://etherpad.openstack.org/RFC-API-Guidelines
On PUT/POST:
* PUTs create things
* POSTs modify existing things
Quite a debate that triggered :)
Looking at the swift API, the semantics of PUT conform just fine to the
HTTP spec. You do PUT on the URI of the resource and the resource gets
created if it didn't already exist.
OTOH, POST to update the object's metadata doesn't make much sense. We
don't "accept the entity enclosed in the request as a new subordinate".
PATCH[1] would probably have made more sense.
The spec is actually quite clear on the different between PUT and POST:
"The fundamental difference between the POST and PUT requests is
reflected in the different meaning of the Request-URI. The URI in a
POST request identifies the resource that will handle the enclosed
entity. That resource might be a data-accepting process, a gateway to
some other protocol, or a separate entity that accepts annotations.
In contrast, the URI in a PUT request identifies the entity enclosed
with the request"
So, perhaps the guidelines should be:
* Either POST or PUT creates things, depending on the meaning of the
request URI
* PUT or PATCH modifies existing things
IMHO, if any of the existing APIs don't conform exactly to the
guidelines, it's not a big deal. The guidelines should aim to correct
past mistakes to make sure new APIs don't inherit them.
Finally, FWIW here's a couple of attempts we made to describe some
RESTful API design guidelines:
http://readthedocs.org/docs/restful-api-design/en/latest/
http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide
Cheers,
Mark.
[1] - http://tools.ietf.org/html/rfc5789
_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp
