Difficulties in API design: Domain

Posted by Riaas Mokiem on April 24, 2020

In this series of articles, I’d like to address some of the difficulties that occur during the design of REST APIs. This article is about difficulties with determining and understanding the domain. In the previous article, I discussed the difficulties with resources, which you should express in terms of the domain. This requires you to determine what domain is relevant to your API and understand it fairly well. This makes the domain an important part of API design.

What is a domain?

In general, a domain refers to an area of expertise or knowledge. In practice, the domain provides the most specific, commonly understood description of functionality. You can see that there is a balance here. A domain is both specific and commonly understood. You can also look at how the domain is defined, to better understand what it is.

How do you define a domain?

One way to define a domain is through practical experience. This requires people that have achieved a common understanding of the specifics in their domain. They can achieve this by spending a long time interacting with many different people in that domain. You typically call these people domain experts. The resulting domain would still be somewhat vague as it is a personal interpretation of each domain expert. If you consult multiple such domain experts, you can still gain a good understanding of the domain.

Another way to define a domain is through standardization. There may be commonly used standards that express their functionality in specific ways. Since people commonly use these standards, they will also understand its terminology. This allows you to define the domain much more concretely as it is based on standards. You can also understand the domain much faster as it only requires an understanding of the relevant standards and protocols, making it easier to become a domain expert.

In practice though, you often define the domain through a combination of the two. There are often competing standards for the same functionality. This means there isn’t a single standard that is common enough to provide a common understanding of the domain. So it requires people that can abstract away what these standards have in common, how they are applied in practice and what may still be missing from them. These people can use their experience to then define the domain. This also shows that the actual definition of a domain will usually be inherently vague, sometimes to the extent that you can’t even provide a name for the domain (though this is usually not a problem).

Why use the domain for REST APIs?

The resources in REST APIs define a contract to its consumers. It is important to describe them in a way that is understandable to these API consumers and that does not violate the contract. Since you can express functionality in a way that people will commonly understand by using the domain, we can allow our API consumers to understand our resources by expressing them that same way.

The domain also provides a very wide view of its functionality. It is not limited to the interpretation of a single person or software implementation. This means that the domain includes all functionality that is relevant within the domain, regardless of whether your own product includes that functionality as well. When you express your resources in terms of the domain this has another benefit. If you need to implement more functionality from that domain, your resources will allow for this. This means you do not need to violate the contract with your API consumers to evolve your API. In practice, it is impossible to ensure that you never have to violate your contract but it’s still good to reduce how often you need to do this as much as possible.

Another reason to use the domain when designing REST APIs is to easily learn how things are supposed to work in that domain. This provides a better understanding of what you need to implement in your product and for your API and should improve the implementation as a whole.

Domain Engineering

Domain engineering (or product line engineering) is a method of software development that has a strong focus on achieving software reuse. The domain is the key to this software reuse, with each system only providing a variation on the domain-specific implementation. This aligns nicely with the REST constraint of Uniformity of Interface which requires you to create your architecture as general as possible. This allows for as much software reuse as possible, just like with domain engineering. This software reuse has the added benefit of not only increased productivity but also higher consistency.

The design process for REST API resources follows a process similar to domain engineering. This shows that some of the techniques from domain engineering are applicable to our design process. But it also shows that the domain is not just relevant for REST APIs. You can apply it to the design and implementation of any product. So it’s clearly beneficial to gain a deeper understanding of the domain whether you’re implementing a REST API, a standalone application or something else entirely.

What is your domain?

When you apply the software engineering principle of Separation of Concerns to your product, its API will likely only cover a single domain. It will usually also need to interact with other domains though. In practice, you may not always be able to name your domain. If you can name or describe the domain, you can look for domain experts for that domain. If you can’t name or describe the domain, you can look for people with a lot of experience with the functionality you’re implementing, from a wide range of use cases (like consultants or specialists from a support department, not the end-users of the functionality). These people are likely to be domain experts and you can rely on them as such. These domain experts can help you define the boundaries of your domain and determine exactly what types of interactions you may have with other domains.

Overcoming the difficulties

Here are some tips that may help you overcome this difficulty during your next API resource design:

  • Identify the main domain for your API early on.
  • Find and involve domain experts early on.
  • Understand your main domain early on.
  • Look into the techniques used in domain engineering to improve your design process.

About the author: Riaas Mokiem

More Posts