Open Stack

On Oct 27, 2011, at 8:56 AM, George Reese wrote:


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


Wow, I seem to have struck a nerve there George which was not my intent.  To add some context, I was under the impression that we're simply having a discussion here about versioning and extensibility in general, in order to help shape our future APIs in a consistent manner.  I don't think that we're re-inventing our current API design, more than discussing how it should evolve. We're also not talking about any particular API (identity, compute, image, object store), but simply discussing things in general in the hopes of moving to some consistency.

Overall, I like the idea of push but it's difficult to scale and techniques like atom have proven themselves.  I don't think that the use case is extraneous or imaginary, in fact, I presented two APIs that use the technique, today in production, at scale.  In the netflix case, I'm simply pointing out that they go out of their way to support variants, precisely to support the browser case.

-jOrGe W.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack/attachments/20111027/71109acf/attachment.html>