[Openstack] API Versioning and Extensibility

Jorge Williams jorge.williams at rackspace.com
Thu Oct 27 13:11:09 UTC 2011


Response inline:

On Oct 27, 2011, at 12:50 AM, Bryan Taylor wrote:

> On 10/26/2011 04:45 PM, Jorge Williams wrote:
>> 
>> On Oct 26, 2011, at 1:19 PM, Bryan Taylor wrote:
>> 
>>> So no pdfs or excel spreadsheets without conneg.
>> 
>> But PDFs and excel spreadsheets are precisely why you want variants!
> 
> Reports and spreadsheets are presentation layer resources that should come from control panels and dashboards and not from a web services API layer.
> 
> In fact, it's with some reluctance that I even suggested having HTML  in the services layer, but we said an API goal was to target developers eyeballing our data formats in a browser. HTML is the best media type to use for this, leveraging the <pre> element, perhaps with some syntax highlighting eye candy.
> 
>> "Here's my usage stats for 2009...
>> 
>> http://usage.api.acme.com/v1.0/jorgew/2009/usage.pdf"
> 
> That shouldn't be coming directly from an openstack API.
> 
> We're actually building a usage service on top of OpenStack and we don't have any PDFs in it. Dashboards, control panels, BI systems etc, should host that resource, not our APIs.
> 
>> You mean to tell me that I can't send that out as an e-mail? Instead I
>> have to say
>> 
>> "Please run this command to see my usage stats for 2009
> 
> Our use case is to show *developers* what the openstack API payloads look like, not to deal with arbitrary end user presentation desires.
> 
>> curl -H "Accept: application/vnd.acme.com+pdf;version=1.0"
>> http://usage.api.acme.com/jorgew/2009/usage"
> 
>> That seems silly to me, we're missing an important feature, the ability
>> to click.
> 
> We are adding an important feature by leaving it out: separation of presentation and data.
> 

In this case you can think of the PDF or excel spreadsheet as simply an alternate representation of the data.  Providing these alternate representations can lower barriers for a lot of clients and personally I think they make sense in some cases.  It's a pattern I've seen used quite successfully.

That said,  I'm not to worried about generating PDFs from our current APIs because we're just not likely to run into that use case.

What I'm more worried about is being able to support things like feeds. A feed can be an alternate representation of an existing collection of servers, for example, and here again we have to deal with the browser as a user agent, that may not participate in the content negotiation process as we'd like.  The <pre> element approach your suggesting won't work in this case either.

The current, load balancer, API uses feeds as an alternate representation for most collection types so that you can track changes, here's an example call.

http://docs.rackspace.com/loadbalancers/api/v1.0/clb-devguide/content/List_Virtual_IPs-d1e2809.html

The API uses a variant (.atom).

You also see this pattern in stuff like the Netflix API as well See /users/{user_id}/feeds in:

http://developer.netflix.com/docs/read/REST_API_Reference

Here the parameter output=atom and a (read only) token is placed in the URI as well, so that one can get access to the feed from a browser.

-jOrGe W.










More information about the Openstack mailing list