<html><head></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><br><div><div>On Oct 27, 2011, at 8:11 AM, Jorge Williams wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><div>Response inline:<br><br>On Oct 27, 2011, at 12:50 AM, Bryan Taylor wrote:<br><br><blockquote type="cite">On 10/26/2011 04:45 PM, Jorge Williams wrote:<br></blockquote><blockquote type="cite"><blockquote type="cite"><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite">On Oct 26, 2011, at 1:19 PM, Bryan Taylor wrote:<br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite">So no pdfs or excel spreadsheets without conneg.<br></blockquote></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite">But PDFs and excel spreadsheets are precisely why you want variants!<br></blockquote></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite">Reports and spreadsheets are presentation layer resources that should come from control panels and dashboards and not from a web services API layer.<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite">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.<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite"><blockquote type="cite">"Here's my usage stats for 2009...<br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><a href="http://usage.api.acme.com/v1.0/jorgew/2009/usage.pdf">http://usage.api.acme.com/v1.0/jorgew/2009/usage.pdf</a>"<br></blockquote></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite">That shouldn't be coming directly from an openstack API.<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite">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.<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite"><blockquote type="cite">You mean to tell me that I can't send that out as an e-mail? Instead I<br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite">have to say<br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite">"Please run this command to see my usage stats for 2009<br></blockquote></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite">Our use case is to show *developers* what the openstack API payloads look like, not to deal with arbitrary end user presentation desires.<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite"><blockquote type="cite">curl -H "Accept: application/vnd.acme.com+pdf;version=1.0"<br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><a href="http://usage.api.acme.com/jorgew/2009/usage">http://usage.api.acme.com/jorgew/2009/usage</a>"<br></blockquote></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite"><blockquote type="cite">That seems silly to me, we're missing an important feature, the ability<br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite">to click.<br></blockquote></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite">We are adding an important feature by leaving it out: separation of presentation and data.<br></blockquote><blockquote type="cite"><br></blockquote><br>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.<br><br></div></blockquote><div><br></div><div>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.</div><br><blockquote type="cite"><div>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.<br><br>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.</div></blockquote><blockquote type="cite"><div>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.<br><br><a href="http://docs.rackspace.com/loadbalancers/api/v1.0/clb-devguide/content/List_Virtual_IPs-d1e2809.html">http://docs.rackspace.com/loadbalancers/api/v1.0/clb-devguide/content/List_Virtual_IPs-d1e2809.html</a><br><br>The API uses a variant (.atom).<br><br>You also see this pattern in stuff like the Netflix API as well See /users/{user_id}/feeds in:<br><br>http://developer.netflix.com/docs/read/REST_API_Reference<br><br>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.<br></div></blockquote></div><div><br></div><div>THE API SHOULD NOT BE SERVING ATOM CONTENT!!!</div><div><br></div><div>I am so damn irritated with the state of the OpenStack API. </div><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>We need innovation in pushing data to API consumers.</div><div><br></div><div>We don't need people re-inventing API design best practices to suit extraneous use cases.</div><div><br></div><div>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.</div><div><br></div><div>-George</div><div><br></div><div>
<span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Helvetica; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; font-size: medium; "><div>--<br>George Reese - Chief Technology Officer, enStratus<br>e: <a href="mailto:george.reese@enstratus.com">george.reese@enstratus.com</a> t: @GeorgeReese p: +1.207.956.0217 f: +1.612.338.5041<br>enStratus: Governance for Public, Private, and Hybrid Clouds - @enStratus - <a href="http://www.enstratus.com/">http://www.enstratus.com</a><br>To schedule a meeting with me: <a href="http://tungle.me/GeorgeReese">http://tungle.me/GeorgeReese</a></div></span>
</div>
<br></body></html>