Hi Mark, I just wanted to clarify to the reasoning why we use POST for metadata modification in Swift. In general I totally agree that PUT/POST should be used for creation (PUT when you know the identification of the representation, POST when you do not). And PUT should be used when modifying the representation. The problem is that in swift, the representation of an object is both the object data, and the metadata for that object. In fact, PUT works fine for update, you just have to re-upload the entire file and the metadata, even if all you want to change the metadata. That is why to change just the metadata, we implemented it in POST.
-- Chuck On Mon, Sep 19, 2011 at 1:03 AM, Mark McLoughlin <mar...@redhat.com> wrote: > 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 > _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
