Documentation Driven Development - Part 1

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
    • A JavaScript front-end engineer using a generated DDD API access file should not look outside of this file to access the API
    • 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. 

Case Study

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...



11 May 2018

Technology English

by John

Acrontum Team Spotlight #1: Jan

We are excited to kick-off our team showcase with one of our oldest Team member. He has been working at acrontum since 2015 and is one of our most renown devs, Jan!

  • First Name: Jan.
  • Country of Origin: Germany / Denmark.
  • What I do: Incredibly difficult coding stuff. Besides that, some full-stack development and technical concepts. 
  • What I like about acrontum: The possibilities to introduce your own thoughts and ideas as well as a super awesome team! 
  • Hobbies: Boarding, playing games, football.

07 May 2018

Team English

by Katty

Recap: EDCH 2018 - Editorial Design Konferenz in München

Oder: was hat Editorial Storytelling mit UI zu tun?


Zweieinhalb Tage, mehr als 70 Sprecher, vom unveröffentlichten Indie- bis zum arrivierten Zeit-Magazin, junge Illustratoren und erfahrene Magazin-Denker, gelangweilte Modefotografen, Datenjournalisten die Feuer und Flamme sind für das, was sie tun. Klassische Typografen, „Wir sind Journalisten“ und Infografiker: alle versammelt in der alten Kongresshalle in München.

Die bekannten Gesichter der Branche sind auch da. Wirklich interessant aber sind Projekte wie republik, Büros wie yaay, Magazine wie Missy, the Mold oder Weapons of Reason, Fotografen wie Claudia Kent.

Und, ja: was hat das alles mit der Entwicklung und Gestaltung von nutzerzentrierten, smarten User-Interfaces zu tun? Das: wie bei Walden muss ein bekanntes Thema neu gedacht und klassisch verpackt werden, muss die eine Idee konsequent dekliniert werden (das neue Erscheinungsbild von Isuzu) und wie bei dem von Verena Gerlach gestalteten Buch „Houses of Taswir“ braucht der Nutzer eine sehr genaue visuelle Anleitung dessen was zu lesen bzw. zu klicken ist.

„Storytelling“ ist also nicht nur ein redaktionelles Werkzeug, „Storytelling“ ist auch ein Werkzeug UIs verständlich und funktionell eindeutig aufzubauen, sie in ein Corporate Design einzubinden und so zu gestalten das der User sie gerne nutzt.

Illustration: Son Luu Vu hier und hier 


14 Mar 2018

Design Deutsch