Tips

Using a Domain Model for API Documentation

Feb 03, 2017
using_a_domain_model_for_api_documentation.jpg
3.5 min read

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?

 

Book - Implementing Domain Driven Design by Vaughn VernonWould 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 draw.io 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.

 

1*H_fOFIlv5fxvPgdXjFwpDw.png

 

 

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


 

Did you know that about 63% of app downloads come through search on the App Store?

apple_search_ads-2.jpg

 

Find out more about App Store Search and Ads

 

 

Share this article
Ross Huggett

Author Ross Huggett

I’m a developer with nineteen years experience designing and building software. I'm always trying things out and learn something new every day, but I also find that many of the lessons of the past still apply.

View more posts by this author

FREE WHITEPAPER

Challenges and opportunities in ARToolKit development.

The explosive rise of augmented reality presents a number of opportunities and challenges for developers. Learn more about the technicalities of AR and AR applications, as well as:

•  AR development software such as ARKit, ARCore, Daqri-ARToolkit and more.
•  The industries AR applications will transform.
•  Considerations in building an AR Toolkit.
•  The future of AR development.
Get your free whitepaper here