In this installment of my REST series I will take on the train wreck, which some people call REST API documentation. Of course some form of documentation is necessary but I am growing more and more disappointed with most current solutions. Tools like Swagger or Apiary can be used to create some sort of documentation, but they sure as hell don’t describe REST APIs.

In this series:

1. Introduction
2. Misuse of URIs
3. Not linked enough
4. Leaky business
5. Resources are application state
6. REST “documentation”
7. Versioning

Sum of all sins

I tend to think that most mistakes made when discussing REST boil down to the misunderstanding of the identifier but also neglecting the other constraints. There are great tools out there like API Blueprint, Swagger or RAML, but they have a significant flaw in common - they are URI centric.

I admire how most tools take an approach complete with steps for design, testing and API security but in the end the client and server usually rely on URI hierarchies.

Here’s a screenshot from sample Swagger petstore API. It’s nice that URI templates are used, but that’s where the good ends. This kind of API documentation encourages developers to code against rigid URL structures. Also most of these tools don’t promote the use of links, which means that at every step in the interaction with the server clients must be aware of the entirety of the API and the documentation also gives little information on the next possible state transfers.

Web API déjà vu

A coffin to the most “REST documentation” tools that I have seen is the idea of generating client and server code. I’ve recently looked at AutoRest to generate client code from Swagger. It’s quite neat and works just fine. You run the executable, pass in the Swagger URL and the program produces a whole lot of code, which indeed works perfect with the API. But it has little to nothing to do with REST.

Haven’t we seen that before?

You guessed it: WSDL. The infamous Web Services Description Language, which in it’s latest incarnation is about as old as the first mention of REST. And it’s by no means the first attempt at web services. Haven’t we just come full circle?