In this series of articles I’d like to address some of the difficulties that occur during the design of REST APIs. This first article is about difficulties with defining resources. Resources are the key abstraction of information in REST which makes them an important part of API design.
What is a resource?
The main problem with REST API design is that it can be quite difficult to understand what a resource is. It is a vague concept, making it hard to define them. For a REST API, the resources should be relevant things that are as suitable as possible for the functionality you want to provide.
Domain-based resources
The description above is still too vague as it may result in wildly different resource definitions that actually refer to the same resource. This is especially true when the resources are defined by different teams or even companies. You don’t want to have to fundamentally change your resources in the future to align these resources again. Defining your resources in terms of the domain of your functionality can help avoid this problem since it provides a wider perspective on the resource’s functionality.
You are also less likely to overlook important details than if you express the functionality of a single system since it may not support all features in the domain. Features that you might want to implement in the future.
So we can now say that resources should be relevant things within the domain of your functionality. Inherently, these things within the domain should be as suitable as possible for the functionality you want to provide.
Again, what is a resource?
Of course, this still begs the question; when is a thing relevant enough to be a resource? This also depends heavily on the domain of your system. Let’s look at 2 examples that illustrate how this could influence similar resources in different systems.
Example 1: A webshop specialized in books
First, you might have a system for a web shop that sells books. This system will require an API that provides information about books. An obvious relevant thing here is a book so we can easily call this a resource. Generally, books are published by a publisher. This seems like information that people buying a book may want to know. Though generally, people buying books from this web shop only need this information in the context of a book. So it’s not relevant enough to make it a separate resource within the domain of web shops. In this case, you should decide to directly include the publisher’s information in the book resource.
Example 2: A CMS specialized in books
If we now look at a Content Management System that specifically focuses on books. This system will also require an API that provides information about books. The book resource is still a fairly obvious resource for this system. In this domain, there is a stronger focus on providing information. The publisher information is no longer only needed in the context of a book. So the publisher is now relevant enough to be a separate resource. The book resource should still be linked to this resource representing the publisher.
Domain experts
At this point, it should be clear that the domain is quite important for designing REST API resources. Designing your resources in terms of a domain allows you to include domain experts in your API design session. These experts can help you understand the domain and identify what’s relevant enough and what isn’t.
Design process
It’s practically impossible to identify and define the right resources in one go. As you discuss with team members, domain experts and stakeholders, you get a better understanding of the resources involved.
Generally, you will start with the most obvious resources. Then improve them, as your understanding improves. This may involve splitting up, merging together or redefining resources. By the end of your design session, you should be sufficiently satisfied with the resources. This should result in resources that are not likely to require fundamental (backwards-compatibility breaking) changes in the future.
Overcoming the difficulties
Here are some tips that may help you overcome this difficulty during your next API resource design:
- Remember to express the functionality required from your API in terms of its domain(s).
- Define your API resources in terms of their domain.
- Invite domain experts to participate in your resource design.
- Start from the most obvious resources.
- Iterate over your design until sufficiently satisfied.