Suggestions for API

Avatar

Amir Mohammad Saied

7 months ago

Hi,

I'm in the middle of writing a bootleg WADL for the Ohloh API, and the API is great, but something annoying me a little, and that's the way the resources are URIed.

I think that would be far better if the .xml extensions being removed from URIs and the API get more of its food through GET params, rather than URLs. I mean: http://ohloh.net/api/projects/?appkey=foobar&v=1&projectid=1 instead of http://ohloh.net/projects/1.xml?appkey=foobar&v=1&projectid=1

According to the REST definitions the application has to provide one endpoint for each method, but not multiple endpoints for one method (retrieving a project's details is one method, and we need some scoping informations indeed, but those parameters are better to be provided using HTTP's POST or GET).

I guess, the current implementation is on this basis that you prefer to serve static data (which will be (re)generated only on changes and are less-resources-hog) rather than generating them on the fly.

And another thing, IMHO, another improvement (not so important though) is to move the resources base from "http://www.ohloh.net" to something like "http://api.ohloh.net" or "http://www.ohloh.net/api/".

I think when you're providing us a read-only API, making it a truly RESTful one would be great (and easier), cause you could be mentioned in different papers as a great example of a RESTful web service then ;)

Thanks again.

Avatar

Amir Mohammad Saied

7 months ago

Uh, I forgot. Something else, Now, the API represent the response status in entity body of HTTP response, ``HTTP Response Codes'' could play this role better.
Avatar

Robin Luckey

7 months ago

Hi Amir,

Thanks for providing feedback on the API.

The layout of our URIs is pretty much an accident of convention. Our site is built with Rails, and there's strong pressure in Rails to do everything the Rails way. When we started, we definitely had REST and XML in mind, but the URIs were chosen more to satisfy Rails and the browser than anything else.

Using the magic of routing, it's probably possible for us to support any number of URI options, including GET parameters or an /api/ prefix, as you recommend. However, we may be forced to continue accepting our current URIs forever, so a change to something "better" may lead to us supporting two parallel URIs for everything.

I freely admit to being a REST beginner, and I based our API on some examples I found on the web, such as Yahoo's design. A few other users have sent me some additional info since the initial design. I'm open to some improvements, and if you have some good REST design samples I'd be interested in them.

You're right that so far the REST API is read-only. We do intend to become writable at some point, but for simplicity's sake we started with just the presentation.

Regarding errors, I do agree that HTTP response codes are the correct solution, and we do in fact return non-200 codes for errors (at least, that's the intention, and if it's broken it's a bug). We also include the error status in the XML body because a lot of users either ignore, lose, or can't access the response codes. The XML results are just a redundant backup, and offer a readable explanation for problems. I might be misguided in this; I was following Yahoo's example. Our API documenation is not very clear about all of this.

Thanks for your input. We will be making improvements to the API eventually, and feedback from our current users is key.

Robin

Avatar

Daniel / Nazca

7 months ago

Oh a restful api ... I could do with some sleep

Sorry, that was a joke ... never could stand the buzzword craze :P

On the topic of url formats ... I'm currently working my code to accept urls in the pattern http://example.com/section.3/item.2/page.1/

They split them down in to key.value pairs and then process them as virtual paths (in the case of requesting a document) or input parameters (in the case of my dynamic image service) ... and in some cases a mixture of both. While they don't exactly look like standard param passing, they feel much more readable and "pretty" to me than http://example.com/?section=3&item=2&page=1 or /?s=3&i=2&p=1

*shrug*

Avatar

denach

4 months ago

I find this API very useful but there are some features that would make it more handy. It would be nice if more information about the evolution/history would be available, like the several versions(each with its appropriate metrics), a link to the svn repos where you can find a specific version(is hard to implement), etc greetings

Post a Reponse