openstack team mailing list archive

[George Reese <george.reese@xxxxxxxxxxxxx>]

On Oct 27, 2011, at 8:11 AM, Jorge Williams wrote:

> 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.
> 

They may be user-centric representations of the data, but from an API perspective (again, "application programming interface"), any such unstructured data is just a blob. There may be valid reasons for delivering blobs through the API (though as Bryan pointed out, in general, there aren't). But when it is done, it is done irrespective of content type or version of the underlying content unless that data is accompanied with meta-data. Under no circumstances is it about the ability to pull that data through a browser.

> 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.


THE API SHOULD NOT BE SERVING ATOM CONTENT!!!

I am so damn irritated with the state of the OpenStack API. 

There's a nasty habit within the OpenStack community of trying to boil the ocean. And here we are navel gazing over feeds and crap when the API can't yet support the most basic of functionality.

I've worked with just about every damn cloud API out there. I have a very solid grasp on how cloud APIs get consumed, what people have done right, what people have done wrong, and where we need innovation.

We need innovation in pushing data to API consumers.

We don't need people re-inventing API design best practices to suit extraneous use cases.

Version and content desired belong in the headers for request and response. The imaginary crap you are dealing with a) don't require them in a URL unless you are pulling it from the URL bar of a browser, which is NOT an API use case and b) doesn't help you deal with the core functionality of the API that is now OVER A YEAR BEHIND where it should be.

-George

--
George Reese - Chief Technology Officer, enStratus
e: george.reese@xxxxxxxxxxxxx    t: @GeorgeReese    p: +1.207.956.0217    f: +1.612.338.5041
enStratus: Governance for Public, Private, and Hybrid Clouds - @enStratus - http://www.enstratus.com
To schedule a meeting with me: http://tungle.me/GeorgeReese

Attachment: smime.p7s
Description: S/MIME cryptographic signature