Recently Mark Baker tweeted about a Nokia REST API project in github:
In particular the following section in the documentation:
Biggest advantages noticed is that the API itself becomes the documentation of the API
- Without HATEOAS developers would get data, go to a documentation, and figure out how to build the next request
- With HATEOAS developers learn what are the available next actions
Steve Jones from CapGemini picked up on this in a recent blog posting:
Either of these would get me firing you I think. I'm a big fan of documentation and I'm a big fan of design. What I'm not a big fan of is people who treat the design process as a series of abstract steps when the only thing that matters is the next step.
Steve has mentioned before that he believes IT values technology over thought and he states that in some ways this Nokia text helps to illustrate that point again: thinking and design are dead or dying in IT. He thinks that there are people who don't value design any more and are continually undermining it as an important part of the development process.
Lets be clear, having clear documentation available is important. What would be poor would be two things:
- Having to wait for someone to build an application before I can start writing a client for it
- Having documentation that is some sort of 'mazy of twisty passages' where you only see one step ahead
According to Steve, there is a push for code-centric solutions rather than design-centric and particularly around REST and HATEOAS. Having documented APIs for services enables a designer to not only map out what they want to do but how they are going to do it, and particularly before any services may have been implemented. Steve indicates that with the aforementioned (REST) approach a designer has to continually switch between API, code and pseudo-design, which is inefficient to say the least. Given what he's seeing in the enterprise, he states that this current trend is retarding IT and impacting the maintainability of REST and other solutions.
This is part of my objection to REST, the lack of that up-front work before implementation - if I have separate client and service teams I don't want to run a waterfall project of 'service finishes, start client' and if those are two separate firms I want to be able to verify which one has screwed up rather than a continual cycle of 'its in the call response' and 'it was different yesterday'. In other words I'd like people to plan for outcomes.
Steve's not against using REST for the implementation, though. He just believes that the current approaches he sees (exemplified by the Nokia API) don't help in the important design stage and they lead to a Travelling Salesman approach:
If I don't know the route to get things done and am making a decision on the quickest way one node at a time then I'm really not looking at the efficiency of the end-to-end implementation just the easiest way to do the next step.
One of the commenters on Steve's blog has this to add to the discussion:
I see a similar thing with any public-facing API, whether REST, or library, etc. Developers have embraced the (good) idea of very short cycles in all they do. Everything is in iterations and, for some reason, developers think upfront design isn't important, or is even bad. When working behind an API, evolutionary design is more acceptable. But public APIs need to be more or less correct out of the gate. They can evolve in some ways (eg, extension), but refactorings put an unrealistic burden upon the users.
One of the things Steve calls for around REST is a standard practice for documenting RESTful APIs along with an execution sandbox, as pointed out by another commenter, and not just rely on HATEOAS.
