Using a Domain Model for API Documentation


20th January 2020


5 min


Dale Jones

This item was written by Ross Huggett.

I was recently asked to do some domain modelling for a project I was working on. After years of practicing outside in Test-driven development (TDD) and using it as a design tool‚ the first thing I asked myself was: what would it be like to go back to the design-first philosophy? Would a fluent API still emerge and would integration be proved right from the start of the development? I was curious to find out.

User scenarios came in from multiple sources – stories in Jira‚ discussions in Basecamp and UI designs done in Sketch. I started to think about where the model might add most value to the project.

Would it give the developers a single view of the domain and what data made up the individual real-world concepts that needed to be modelled in the software?

Would the product owner be able to understand it‚ even though it was a technical document? It needed to include the vocabulary of the domain so that it could be used to communicate to non-technical stakeholders. I had some previous DDD experience and had read Vaughn Vernon’s book Implementing Domain-Driven Design.

How would I use it? Would it be useful when I went to create the API documentation and server mocks in apiary? I could see it being useful simply as a quick reference document to be consulted when answering questions from the project stakeholders.

I had used various modelling tools in the past including Enterprise Architect and OmniGraffle but I wanted to make it easy to share the model without the need to install anything so I decided to give browser-based a try. It felt lightweight and simple to use‚ and allowed me to start drawing very quickly. I liked the Google Docs integration too.

I found myself using the UI designs primarily as a source for nouns and verbs that I would base my real-world concepts on. The project was a mobile app in which this had been clearly defined through a series of screens showing how they interacted with one another.

[object Object]

 I also found myself leaning heavily on a domain model I had created for a previous project‚ which featured similar concepts like users‚ jobs and requests which were generic enough for me to reuse in this model. I’ve recently written an open source web app too‚ which I used as reference because it has a REST-based API.

I wanted to keep the model as simple as possible so I decided to focus solely on inheritance and composition between the concepts. Coming from a Java background‚ I generally favour composition over inheritance‚ but‚ of course‚ it depends on the situation. I also decided to drop the behaviour element of a domain model and just concentrate on the data‚ since I’ve found behaviour is better suited to a class diagram (something I may blog about later).

So I went about furiously modelling and creating concepts before realising they were getting too big‚ creating abstractions‚ realising they might be wrong and subsequently deleting them. I noticed the bounded contexts starting to appear and the language of the domain beginning to build; this could be used later to define the ubiquitous language in DDD speak. 

I discovered a limitation in in that‚ unlike Google Docs‚ it does not facilitate suggestions or comments; this was frustrating as this feature provides a useful way to provide feedback on a document without interrupting the author too much. The folks at said they were working on it though.  

After I had finished going through the UI design and the other sources‚ I felt I had something I could use and so scheduled a meeting with the product owner and project manager to go through the diagram. It was well-received‚ generating some good feedback.

I then moved onto my next task: creating the API documentation. I decided to do this in a tool called apiary‚ which enables its creation based on the API Blueprint standard. It also creates hosted server mocks‚ generated from the responses defined in the document itself‚ which is quite cool.

It has its own editor which provides validation and the ability to run tests‚ further validating the responses to ensure‚ for example‚ the JSON is well formed.

So using the domain model as reference‚ I started writing the documentation. I used the domain concepts I had identified in the model to create the resources. For the request and response examples‚ meanwhile‚ I used the data elements to create the JSON objects. 

Overall‚ I found it to be a good experience because I had done the domain model first. It made the API documentation much easier to write since I based the resources on the concepts I had already identified. I also discovered it was an iterative process‚ making changes to the model where I realised some of my concepts were wrong while writing the examples in the API documentation.

As we replace the mocks with the real implementation‚ I can see further changes happening.

Thanks to Alan Morris and Sam Miller at hedgehog lab who helped me put this blog together.