Blog

Documentation Driven Development - Part 1

15 Nov 2018

Technology English

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

 

 

by John



Die Medien berichten tagtäglich über Blockchain, potenzielle Anwendungsbereiche und hochinnovative Startups. Doch was genau bedeutet "Blockchain" und welche Eigenschaften machen diese Technologie so vielversprechend?

Zusammenfassung

Eine Blockchain bietet fälschungssichere Transaktionen über digitale Technologien sowohl in öffentlichen wie auch privaten Netzwerken. Vereinfach gesprochen kann die Blockchain als Kassenbuch über Transaktionen beschrieben werden. Im Gegensatz zu herkömmlichen Kassenbüchern, werden hierbei allerdings kryptographische Verfahren genutzt, um alle privaten Daten durch Hashfunktionen zu verschlüsseln.

Das nachträgliche Fälschen von Transaktionen ist unmöglich, da dadurch sämtliche später ausgeführten Transaktionen zerstört würden beziehungsweise manipuliert werden müssten. Eine solche Änderung wäre für alle anderen Teilnehmer im Blockchain-Netzwerk sofort sichtbar. Eine dritte Partei mit Kontrollfunktion, beispielsweise eine Bank, ist aufgrund des technologischen Aufbaus nicht mehr notwendig.

Basis
  • Peer-to-Peer: dezentrale Datenbank, verteilt auf allen Mitgliedern (Peers) des Netzwerks
  • Mining Node: Teilnehmer des Blockchain-Netzwerkes zur Zusammenfassung und Validierung von Transaktionen.
  • Hash-Wert: verschlüsselte Prüfsummen aus Datensätzen, erzeugt durch Einweg-Algorithmen
  • Hash-Baum: paarweises Verschlüsseln von Hash-Werten bis zum Top-Hash
  • Top-Hash: letzter („oberster“) Hash-Wert eines Hash-Baumes
Details

Eine Blockchain besteht dem Namen nach aus (Daten-)Blöcken, welche eine Kette (Chain) bilden:

  • Block: Datensammlung für eine begrenzte Anzahl an Transaktionen. Besteht bei der Bitcoin Blockchain unter anderem aus einem Hash Pointer, welcher auf den vorherigen Block zeigt, einer Variablen zur Lösung einer hochkomplexen Rechenaufgabe sowie Transaktionsdaten und Zeitstempel.
  • Chain: fälschungssichere Verkettung der Blöcke durch diskrete, fortlaufende Abhängigkeit zwischen einander.

Ein Block besteht aus mehreren Transaktionen, welche von sogenannte „Mining Nodes" validiert werden. Bei der Block-Erstellung werden Transaktionen paarweise so lange über Einweg-Algorithmen verrechnet, bis der einzelne Top-Hash dieses Hash-Baumes berechnet wurde. Damit sind diese Transaktionen fest im Block verankert. Bevor der aktuelle Block jedoch fertig gestellt ist, muss die Verkettung zwischen dem vorherigen sowie dem nachfolgenden Block als Hash-Wert sichergestellt werden. Dieser neue Hash („New Hash“) wird aus drei Faktoren errechnet:

  1. Hash-Wert des vorherigen Blocks in 256 Bit
  2. Top-Hash der berechneten Transaktionen
  3. Zufällige Variable zur Lösung der vorgegebenen Funktion

Sobald der „New Hash“ errechnet wurde, wird der gesamte Block mit allen bearbeiteten Transaktionen an alle Peers (Bitcoin: Nodes) veröffentlicht. Der Hash-Wert dient außerdem als Berechnungsgrundlage für den kommenden Block.

Bestätigung

Sobald der nächste Block auf Basis des vorangegangenen erfolgreich berechnet sowie veröffentlicht wird, gilt der vorherige Block als bestätigt („1 confirmation“). Dieser Vorgang schützt die Integrität der Blockchain, sodass nur Transaktionen mit 3 oder mehr erfolgreichen Bestätigungen als vertrauenswürdig angesehen und daher vollzogen werden. Zusätzlich kann jeder Teilnehmer des Netzwerkes auch im Nachhinein noch die Korrektheit eines Blocks errechnen.

Sicherheit

Durch die fortlaufende Verkettung aller historischen und zukünftigen Blöcke durch kryptographische Verfahren ändert jegliche noch so kleine Änderung einer Transaktion eines historischen Blocks die Hash-Werte aller darauffolgenden Blöcke. Durch die Dezentralisierung des Netzwerkes ist eine Fälschung daher nicht möglich.

Anwendung

Bereits im Jahr 2017 nahm die Aufmerksamkeit sowie Begeisterung für die Blockchain-Technologie Fahrt auf und war beispielsweise auf der größten Digitalmesse Europas, der DMEXCO, das alles beherrschende Thema. Neben den etablierten Anwendungsmöglichkeiten als Basis für sogenannte Kryptowährungen wie Bitcoin, Ethereum und Monero, wird die Blockchain-Technologie mit ihren spezifischen Eigenschaften auch als Grundlage zur Vertragsgestaltung zweier Parteien diskutiert.

Diese „Smart Contracts“ genannten Protokolle bieten automatisierte Vertragsgestaltung und -erfüllung mit durchgehender Anonymität der Vertragspartner untereinander, sei es bei Versicherungsverträgen, Immobilienverkäufen oder im Gesundheitswesen. Auch hier ist eine dritte Partei zur unabhängigen Vermittlung durch den Einsatz von Blockchain obsolet geworden.

Darüber hinaus ist aufgrund der unmöglichen Fälschbarkeit sowie der Anonymität ein Einsatz der Blockchain bei Parlamentswahlen oder Volksabstimmungen durchaus denkbar.

Aktuelle Beispiele
  • carVertical: Aggregation & Speicherung aller Fahrzeugdaten von PKWs in einer Blockchain zur Vermeidung von Tachomanipulation, Unfallbetrug und ähnlichem.
  • KodakCoin & KodakOne: Kryptowährung & Blockchain zur optimierten Kontrolle von Bildrechten, inklusive Lizenzkäufe sowie Rechtemanagement für professionelle Fotografen, Agenturen sowie Hobbyknipser.
  • Bitwala: verschlüsselte, sicherer und schneller Geldtransfer ins Ausland sowie Bitcoinfähige EC-Karte für Käufe im Einzelhandel.
  • Storj: dezentralisierter Cloudspeicher mit End-to-End Verschlüsselung.
  • Ujo: direktes und sicheres Rechtemanagement sowie vertrauenswürdige Lizenzvereinbarungen zwischen Musikern und Streamingportalen oder Endverbrauchern unter Auschluss von Verwertungsgesellschaften (GEMA) und Plattenfirmen.

Wir verfolgen mit Spannung die weitere Entwicklung der Blockchain-Technologie und der Use Cases, die zur Zeit tausendfach aus dem Boden sprießen. Die Zeit wird zeigen, welche Anwendungsfälle sich nachhaltig am Markt durchsetzen werden.

Kontakt

Wir stehen Ihnen für Fragen oder Anregungen jederzeit gerne zur Verfügung.

by Julien