subbu.org

Here is a well-designed REST API from Netflix that starts with this in the overview:

Designed to be resource centric, the API keeps the data references for resources in the URL path, to the right of the host name, and uses links to tie together related resources. Method information goes into the standard HTTP verbs.

This is first API that I came across that has linking stated so prominently. Kudos to the Netflix team.

There are a few odd wrinkles in the API that I wish are not there:

• Status code and message duplicated in representations: Why duplicate HTTP status line within representations? The same goes for etag values in representations. I remember the Astoria team wanted to do something similar for collection feeds, and Netflix seems to have generalized this further. Seems unnecessary.
• Status code 204 when a resource created: This is incorrect. 204 is reserved for cases when the result of POST can not be identified via a URI, and does not apply for successful resource creation.
• Boxcarring (aka batch) via POST: Again, this is unnecessary, and boxcarring could be addressed by proper resource modeling.
• Collections: Netflix could have simplified collections by using Atom. Instead, they chose to invent their own format. (Note: You will find the same in some soon-to-be-released Yahoo APIs for the social platform).
• Unix time: Why use Unix time instead of RFC 3339?

When compared to other APIs out there, these are very minor issues.

It is also nice to see this API using the View Pattern for partial representations in stead of inventing more complicated syntax.