I’m neck deep in RESTful APIs. I’m in the late stages of designing the Analytics 2.0 APIs in my job as Product Owner for Analytics at Rally Software. I’m in the early stages of designing an API for the Lean Software and System’s (LSSC) Kanban Benchmarking and Research Program… and just today, I met with Steve Speicher and others from the Open Services for Lifecycle Collaboration (OSLC) to talk about joining one of the working committee designing RESTful services for data interchange.
I have been struggling with one aspect of “pure” REST APIs as defined by the four constraints in Roy Fielding’s dissertation. In particular, it seems that almost none of the popular “RESTful” APIs on the internet implement the Hypermedia as the Engine of Application State (HATEOAS) constraint. If the constraint is so critical, as Dr Fielding insists, then why is it so often ignored? The idea is that operations that you perform on a resource should be made visible to clients not via documentation but rather via links in the responses to a few published endpoints. A good citizen consumer of a truly RESTful API will not know the link to transfer bank funds, or approve a leave request, or (any action) on (any resource). Rather, it will “discover” the links for these actions in the initial response to a query against the bank account, or leave request, or (any resource).
My main problem with valuing this constraint as highly as Dr Fielding seems to is that it doesn’t seem to greatly reduce coupling as intended. The client still needs to KNOW that you want to transfer, approve, or (some action). Knowing the link to do so before hand seems like a fractional increase in coupling. That said, if it doesn’t cost too much, it would be nice to follow this recommendation because it would fractionally reduce coupling.
That brings me to my second conundrum. The Analytics 2.0 APIs are all read-only. What “application state” (as opposed to resource state) is there in such a situation? Then today, it finally came to me… the only application state (that I can think of) in a read-only API is around paging. The first page response to a multi-page request should include the link to the second page, and so on. This is particularly useful for Rally’s Analytics 2.o Lookback API because we were already recommending that the requests for the subsequent pages include an additional clause to ensure that the data returned for the subsequent pages is for the same moment in time as the first page. We had little confidence that this recommendation would be followed. Now, I’m specifying that we add a NextPage link to each response. We may also remove the “start” parameter from the API as it enables a tighter coupling than the use of the NextPage link.