 |
 |
I'm not going to defend API keys, but not all APIs are open or free. You need to have *some* way to track usage. There may be alternative ways to implement that, but you can't just hand wave away the rather large use case for API keys. -Ross. On Mon, Dec 2, 2013 at 12:15 PM, Kevin Ford <[log in to unmask]> wrote: > Though I have some quibbles with Seth's post, I think it's worth drawing > attention to his repeatedly calling out API keys as a very significant > barrier to use, or at least entry. Most of the posts here have given > little attention to the issue API keys present. I can say that I have > quite often looked elsewhere or simply stopped pursuing my idea the moment > I discovered an API key was mandatory. > > As for the presumed difficulty with implementing content negotiation (and, > especially, caching on top), it seems that if you can implement an entire > system to manage assignment of and access by API key, then I do not > understand how content negotiation and caching are significantly "harder to > implement." > > In any event, APIs and content negotiation are not mutually exclusive. One > should be able to use the HTTP URI to access multiple representations of > the resource without recourse to a custom API. > > Yours, > Kevin > > > > > > On 11/29/2013 02:44 PM, Robert Sanderson wrote: > >> (posted in the comments on the blog and reposted here for further >> discussion, if interest) >> >> >> While I couldn't agree more with the post's starting point -- URIs >> identify >> (concepts) and use HTTP as your API -- I couldn't disagree more with the >> "use content negotiation" conclusion. >> >> I'm with Dan Cohen in his comment regarding using different URIs for >> different representations for several reasons below. >> >> It's harder to implement Content Negotiation than your own API, because >> you >> get to define your own API whereas you have to follow someone else's rules >> when you implement conneg. You can't get your own API wrong. I agree >> with >> Ruben that HTTP is better than rolling your own proprietary API, we >> disagree that conneg is the correct solution. The choice is between >> conneg >> or regular HTTP, not conneg or a proprietary API. >> >> Secondly, you need to look at the HTTP headers and parse quite a complex >> structure to determine what is being requested. You can't just put a file >> in the file system, unlike with separate URIs for distinct representations >> where it just works, instead you need server side processing. This also >> makes it much harder to cache the responses, as the cache needs to >> determine whether or not the representation has changed -- the cache also >> needs to parse the headers rather than just comparing URI and content. >> For >> large scale systems like DPLA and Europeana, caching is essential for >> quality of service. >> >> How do you find our which formats are supported by conneg? By reading the >> documentation. Which could just say "add .json on the end". The Vary >> header >> tells you that negotiation in the format dimension is possible, just not >> what to do to actually get anything back. There isn't a way to find this >> out from HTTP automatically,so now you need to read both the site's docs >> AND the HTTP docs. APIs can, on the other hand, do this. Consider >> OAI-PMH's ListMetadataFormats and SRU's Explain response. >> >> Instead you can have a separate URI for each representation and link them >> with Link headers, or just a simple rule like add '.json' on the end. No >> need for complicated content negotiation at all. Link headers can be >> added >> with a simple apache configuration rule, and as they're static are easy to >> cache. So the server side is easy, and the client side is trivial. >> Compared to being difficult at both ends with content negotiation. >> >> It can be useful to make statements about the different representations, >> and especially if you need to annotate the structure or content. Or share >> it -- you can't email someone a link that includes the right Accept >> headers >> to send -- as in the post, you need to send them a command line like curl >> with -H. >> >> An experiment for fans of content negotiation: Have both .json and 302 >> style conneg from your original URI to that .json file. Advertise both. >> See >> how many people do the conneg. If it's non-zero, I'll be extremely >> surprised. >> >> And a challenge: Even with libraries there's still complexity to figuring >> out how and what to serve. Find me sites that correctly implement * based >> fallbacks. Or even process q values. I'll bet I can find 10 that do >> content >> negotiation wrong, for every 1 that does it correctly. I'll start: >> dx.doi.org touts its content negotiation for metadata, yet doesn't >> implement q values or *s. You have to go to the documentation to figure >> out >> what Accept headers it will do string equality tests against. >> >> Rob >> >> >> >> On Fri, Nov 29, 2013 at 6:24 AM, Seth van Hooland <[log in to unmask]> >> wrote: >> >>> >>> Dear all, >>> >>> I guess some of you will be interested in the blogpost of my colleague >>> >> and co-author Ruben regarding the misunderstandings on the use and abuse >> of >> APIs in a digital libraries context, including a description of both good >> and bad practices from Europeana, DPLA and the Cooper Hewitt museum: >> >>> >>> http://ruben.verborgh.org/blog/2013/11/29/the-lie-of-the-api/ >>> >>> Kind regards, >>> >>> Seth van Hooland >>> Président du Master en Sciences et Technologies de l'Information et de la >>> >> Communication (MaSTIC) >> >>> Université Libre de Bruxelles >>> Av. F.D. Roosevelt, 50 CP 123 | 1050 Bruxelles >>> http://homepages.ulb.ac.be/~svhoolan/ >>> http://twitter.com/#!/sethvanhooland >>> http://mastic.ulb.ac.be >>> 0032 2 650 4765 >>> Office: DC11.102 >>> >>