Documentation Driven Development - Part 1
15 Nov 2018
At acrontum we made the decision after plenty of careful consideration to adopt a new and growing trend, “documentation driven development” via “swagger” and now the newly updated specification, “OpenAPI 3”.
Documentation driven development (DDD) is not something new (some of its earliest concepts date back to 2011), but up until recently it never had an officially accepted name, nor an industry standard for the world to agree upon. It is the process of describing & designing API's and what one expects as a request and should respond with. This enables a front-end team to easily use an API within their apps and mock the response without an actual API to talk to.
Documentation driven development at acrontum is very simple and essentially boils down to a two high level and basic principles:
- Design the API first, then build it
- The API design must adhere to the OpenAPI Specification (formerly known as Swagger)
- The yaml file can be broken up with swagger-chunk
- The finished result of the API design should be a Yaml or JSON file
- The actual API routes should be built on what is documented in the design
- The client, eg the browser, should communicate with the API via a generated file, built from a tool such as swagger-code-gen
- An endpoint not documented should not exist
- As all routes must be documented, any other routes can be seen as not required &/or dangerous
Adhering to DDD has simultaneously increased development speed whilst solving a growing issue regarding how the front-end and back-end teams both build and communicate. Further more this is not limited to company cross-team dynamics but also expandable to cross-company communications.
A recent project for BMW saw acrontum developing multiple API’s adhering to the aforementioned DDD principles where the main API was consumed by an Angular5 application, also built by acrontum.
Before work commenced, the API’s were designed using the Swagger2.0 spec. Upon the agreed design, both the front-end and back-end team could commence work simultaneously. The front-end team knew how the API would look when complete and could simulate the API using a mock server outputting example content. Conversely the back-end team could pick and choose which routes they wanted to build as and when they felt it right: Not having to build the routes in an order requested by the front-end team resulted in a far quicker time to staging for real testing and higher quality code base.
Change request, as with any project, happen as the client realises new potential. As and when change requests arrive that affect the back-end, the first step was to evolve the API design, ie the DDD file. After publishing the changes to the new API design(s) both the front-end and back-end could pull the updated changes and keep on building.
In addition to this, one of the API’s we built would also be consumed by a 3rd party application and once again, as the API was clearly defined by the DDD principles the said 3rd party could happily mock the API’s responses to build their part without much if any interaction with the API build team.
Looking to the future
DDD has given us some very big gains as described, but what could the future look like and how do we aim to streamline this process yet further.
Currently the API design must be written in a single Yaml file. When the API gets bigger than trivial the need to break the file down into sizeable chunks becomes a must, this is where swagger-chunk comes in. swagger-chunk allows the developer to write many smaller and manageable Yaml files which swagger-chunk then combines together into one.
Swagger-chunk is one step in the right direction, but it can be easy to get lost in a myriad of similar looking files. Further more, designing an API does not necessarily depend on skill of a developer if there were an alternative to writing pure Yaml chunks…. Enter the open source project of openapi-gui.
Openapi-gui is a graphical user interface to building the API design. The API designer does not require anything more than a web browser and technical knowledge on what a RESTfull API should be and deliver. In laymans terms, the API design can now be realised by a skilled technical product owner.
At acrontum we have yet to trial this technique and tool in production, but this does not mean we are not designing new processes to trail this, stay tuned for a future analysis...