[Openstack] Guidelines for OpenStack APIs

Mark McLoughlin markmc at redhat.com
Mon Sep 19 06:03:31 UTC 2011


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





More information about the Openstack mailing list