Readme-Driven Development, API first design and Contracts

This night I solved a problem of mine. I am entusiastic about this solution. I think, it will solve a problem for other people, too.

Everyone uses the travis build badges to show their build status.

But I did not find one for docker automated builds. So, I created one.

For me it solves the need to know if my builds run. Not always do I test them with travis before. Not always does this mean they build on docker, when they build on travis.

Readme-Driven Development

When I started implementing, it was already late. I wanted to

• be able to stop any time
• not forget where I was heading
• allow other who would search for it continue my work

So, I started with Readme-Driven Development. I documented all I needed to work on the project, links to the undocumented dockerhub API.

Then, I outlined an architecture. After this, I wrote the draft of an API.

Contracts

This can be seen as a small version of contracts. The idea: We specify the interface we want to have before the implementation. (When I hear this, I think of TDD).

The current API has these contracts:

1. The JavaScript API GET /status/...
2. The AGPL API GET /source
3. The status.svg API GET status.svg?<parameters>

Implementors of these contracts are:

• the server
  • implementing 1, 2, 3
• the status.svg file with JavaScript
  • implementing 3
  • using 1

While I used the status.svg file to formulate the API, it became very clear how to implement the same behavior in the Python server.

This way there is more diversity and fault tolerance.

Learnings

It was a refresing experience to code API and README first. I assume that APIs can implement different contracts. Formulating part of the API as a contract allows this specific implementation to be exchanged. This results in more flexibility and a more specific tailored solution to use-cases.