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.
6 comments:
This isn't an either/or - there's nothing preventing a REST API from having documentation, and (at least in my experience) the best REST APIs provide comprehensive documentation (ideally with an "execution sandbox", so that I can play around as I read).
I completely agree, its why I wrote the article. There is nothing stopping a decent approach being done with REST, it was just depressing that the linked post appeared to miss that point.
It would be great to see a standard practice around REST for this and have mocking (even before a sandbox) as a standard practice.
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.
Wonderful blog & good post.Its really helpful for me, awaiting for more new post. Keep Blogging!
Architects Brisbane | Residential Architects Brisbane
I'm glad I don't work for you Steve and if you were working for me I would have fired you for saying you would fire someone because of their ideas.
Upfront system design and documentation is not only a leftover from the past, but considerably dangerous for any modern iterative approach, included those non agile.
I'm sorry, but if you don't understand this then you can't work for me: keep designing huge systems that aren't able to adapt to business changes.
Roberto,
I humbly disagree that design is not a core part of modern agile delivery, particularly when looking at integrated solutions.
THINKING remains the major challenge in any program not CODING, designing is about spending the thinking time so the code works. In any decent delivery there must be design as that frames how the coding will be done.
Doing 'Agile' without either documentation for support and without design for context is great for people who want to hack a quick disposable solution but woefully inadequate if you want something that actually can adapt to change and which crucially can be supported by someone other that the development team.
The horror of some modern views is based around the 'well I can code it' mentality and 'look I built this small tiny point solution, I could build an ERP'.
Systems that adapt well are systems that have clear clarity of thought, if you think that Fred Brooks was wrong then I suggest you write a paper explaining how that is the case.
Post a Comment