By sandoz on Sep 21, 2007
I noticed that Ohloh has REST-based API to GET representations in XML. Looks like a great start. The URI structure looks good and you are presented with URIs like the following:
But, from the perspective of a consumer, this API could be improved:
- The <response><status>...</status> fragment at the beginning of a representation is redundant and forces the client to unnecessarily process additional XML. Instead document the HTTP status codes. The HTTP status code 200 (OK) is sufficient for signaling success so rather than the root element being <response> it could be <projects> when getting a collection of projects and <project> when getting a project. The HTTP status code 400 (Bad Request) is sufficient for signaling a client error with an appropriate machine processable representation detailing the error.
- URIs are not present in the representations. This forces the client to construct URIs from identifiers in the representation, for example <project><id>1</id>...</project>, which increases the coupling between the client and server and makes it harder for the server to evolve the URIs (if need be) without breaking existing clients.