Occasionally I run across things on the web, this time tweeted by Mark Baker (@distobj), that make me read them several times. The link he tweeted is to this page on a Nokia API and in particular this section...
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
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.
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
This to me is at the heart of the death of design in IT, the lauding of everything as architecture and the massive chasm that appears to be developing between that and writing the code. I'm repeatedly seeing approaches which are code centric rather than design centric and the entire history of IT tells us that this isn't the best way forwards. Don't try me on the 'I just refactor' line as if that is an answer, spending 1 day thinking about a problem and planning out the solution (design) is worth 5 days of coding and 20 days of subsequent refactoring.
I'd really like a developer to be able to map out what they want to do, be able to read the documentation in one go and understand how they are going to deliver on the design. I don't want a developer context switching between API, code and pseudo-design all the time and getting buried in the details.
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. This doesn't mean not using REST for implementation it just means that the design stage is still important and documentation of the interface is an exchangeable artefact. Now if the answer is that you have a Mock of the API up front and a webcrawler can extract the API documentation into a whole coherent model then all well and good.
Because the alternative is the travelling salesman problem. 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.
This current trend of code centric thinking is retarding enterprise IT and impacting the maintainability of REST (and other) solutions. This isn't a question of there being a magic new way of working that means design isn't important (there isn't) its simply a question of design being continually undermined and discarded as an important part of the process. Both of the scenarios outlined in the article are bad, neither represents good practice. Choosing whether your manure sandwich is on a roll or a sub doesn't change the quality of the filling.
Think first, design first, publish first... then code.