In an ideal world, our programs, interfaces, and APIs would not need documentation. Our clients would all be magical beings, able to read our minds and understand precisely what it is our system does and how to use it.
Unfortunately, this is not the status quo today, since many enterprises use hand-written documentation (usually in PDF or Microsoft Word format) in a bid to make life easier for integrating developers. Hypermedia evangelists, in particular, are not pleased with this situation. If we had to compare this to websites, it would be the same as being provided a manual for each site we visit – and like websites, APIs should be self-documenting and give the user with enough information to allow him to use and navigate across API states. Unfortunately, however, many enterprises shy away from not having a “document” – particularly in areas like FinTech – since clients tend to be more conservative in the ways they work and the technologies they adopt.
To add insult to injury, these manual documents are written in a separate sphere from the implementation, sometimes by entirely different departments/teams within the enterprise. As such it is relatively common that synchronization issues occur which are very hard to fix since the manual review is pretty much the only way to identify and correct problems.
At this point many old-school SOAP aficionados rear their heads and make fun of this newfangled REST stuff. “… in our day we had the WSDL!, you could generate everything from the WSDL!, You don’t have a WSDL in REST ha!” And even though SOAP is inferior to REST in many ways, the WSDL is the one thing that was almost universally loved (except maybe by the person who had to author it J) and could facilitate understanding and integration of APIs by clients.
Luckily, REST now has its “WSDL.” Three new emerging technologies: RAML, Swagger, and API Blueprints aim to document the contract that is our API and to do so in a way that is simple and easy to use. For the rest of the article, we will be using RAML for our discussion and examples. However, the same points can be applied to Swagger and API Blueprints. We chose to use RAML since it is straightforward to write (at the time of evaluation) and understand, while at the same time providing constructs which encourage reuse heavily.
What is RAML?
Rest API Markup Language, aka RAML, is an open language designed to document REST APIs which are based on YAML. This means that indentation is used to create structure leaving the document free of braces and other text which is not directly relevant to the body being documented.
My favorite aspect of RAML as a language is that it has a very short learning curve and proper documentation, editors, and tutorials to get developers going. The open nature of the language means that plenty of tooling is being developed in this space. Another great feature is that the language encourages reuse through traits, resource types and other bits and bobs which allow us to define concepts once and reuse across our API stack. This not only saves time but encourages consistency.
The main benefit of using RAML (or any other API Documentation Language) is that we are producing a document that is machine readable. This means that we are adding an extra step toward having some shiny document we can send to prospective clients, but it also means that this same RAML file can be used to generate all sorts of different documentation which can be consumed by different people:
- A simplified version of Management/Evaluation
- Interactive documentation including Sandbox for integrating developers
- Code generation for internal developers
- Test Generation and Verification of endpoints for QA teams and internal developers
- GUI generation for rapid prototyping
And the list goes on.
Contract-first vs Code-first
We can apply RAML to our projects using two approaches: “Contract-First,” i.e., when the RAML file is written before implementation starts or “Code-First,” where the implementation precedes or is done in sync with RAML development. Both have very different use-cases.
Let’s discuss contact-first, first J. In this approach, an effort is made on the API documentation before the coding begins. The main benefit here is that teams will focus on the consumption of the APIs rather than what is available under the hood and take design decisions which will ultimately result in a better experience for integrating clients.
Another benefit is that during the development of the API, tools such as the API Console or other WYSIWYG editors provide a live view of the API as it’s built. This can be mocked and exercised by various team members (UI Developers, Product Stakeholders, etc.) and can provide a very visual way of spotting issues and improve the design. Once the document is complete, this can be used as an integration point between teams – Javascript/UI developers can code against a mocked variant of the RAML file while backend developers can use it to generate code or tests.
We are trying to move all our internal development to a contract-first approach since the only drawback of this approach is that we are adding a small step to the development process. This approach is not always possible, especially with existing projects where there is already a large API footprint. In these cases, a big-bang documentation shift can be hard to justify, and a code-first approach can be adopted.
A Code-first approach does not help improve the overall design. However, there are different benefits. As a starting point, this approach can be applied to our existing code-base to generate documentation and all other associated benefits, with minimal effort. This documentation can provide visibility to teams who might not be operating outside the backend. At phoenixNAP, we have applied this technique successfully using an in-house plugin which generated a RAML file from custom annotations used in the backend of our phoenixNAP Client Portal web application. This internal RAML was used by our front-end teams to improve the communication with the backend developers and to allow us to work together on building a UI and a backend for a task simultaneously.
This plugin was extended to generate RAML from standard Spring MVC annotations and was open-sourced under the Apache 2.0 License and can be found on GitHub.
In the architecture department, the RAML plugin is used within our Spring Boot reference container to allow us to create API-driven proofs-of-concept rapidly. For these internal research projects, development speed is critical since their purpose is to validate or illustrate an approach we plan to take. Rather than having to develop an interface, writing simple APIs which are parsed by the SpringMVC RAML plugin provides us with an interface which we can then use to evaluate the solution. This tooling allows for very rapid prototyping and can also allow us to ship the POC to other departments without having to spend time developing an interface or documentation.
Keeping Things in Sync
One of the drawbacks and in some ways benefits of API documentation languages is that they are separate from the implementation. This puts us in a situation where we might have different sources of “truth” similar to how PDFs and their corresponding Word Documents may end up out of sync as changes are applied to one but not the other.
The most significant difference is that unlike PDF/Word, where a manual review is the only solution, in the RAML world we have tooling that can help us keep these documents in check.
Abao (https://github.com/cybertk/abao/) is a tool which parses the RAML file and executes tests on our endpoints to check if the implementation respects the contract. The SpringMVC RAML parser generates a RAML model from the implementation and compares this to the contract being published. This can be used as a Maven plugin which could trigger a build failure when incompatible scenarios are detected.
Conclusion
API documentation languages are at an exciting stage.
The open and straightforward nature of these languages makes adoption and extension reasonably simple – when we introduced RAML there were minimal issues, and many benefits out of the box. We were able to build our own tools on top of these technologies. As such, there is so much brought to the table that is there really any point to using static documents to document our APIs anymore?