Learn some best practices for using RESTful APIs in domain-driven design (DDD), such as aligning your API with your domain model, avoiding CRUD-based APIs, and using versioning strategies.

Along with versioning, you should document your API well. Implementing Swagger or other API definition and documentation standards will allow your consumers to understand your endpoints and capabilities along with changes between versions. They can even try out endpoints and explore expected inputs and outputs for your API.

Last updated on Jun 14, 2024

What are some best practices for using RESTful APIs in DDD?

RESTful APIs are a common way of designing and implementing web services that follow the principles of Representational State Transfer (REST). They are widely used in microservices architectures, where each service exposes its functionality and data through a uniform interface. However, using RESTful APIs in Domain-Driven Design (DDD) can pose some challenges and pitfalls, as DDD focuses on modeling complex domains and capturing the business logic and rules in code. In this article, we will explore some best practices for using RESTful APIs in DDD, and how to avoid some common mistakes.

1 Align your API with your domain model

One of the key aspects of DDD is to define a domain model that reflects the business domain and its concepts, rules, and behaviors. The domain model should be expressed in a ubiquitous language, a common vocabulary that is shared by the developers and the domain experts. The domain model should also be modularized into bounded contexts, which are self-contained units of functionality and data that have clear boundaries and interfaces.

When designing your RESTful API, you should align it with your domain model as much as possible. This means that your API resources should correspond to your domain entities, aggregates, and value objects, and that your API operations should correspond to your domain services, commands, and events. You should also use the ubiquitous language in your API naming, documentation, and representation, and respect the boundaries and contracts of your bounded contexts. This way, you can ensure that your API is consistent, coherent, and meaningful for both the developers and the consumers.

Add your perspective

LukÃ¡Å¡ M.

Software developer ve spoleÄnosti Seznam.cz. ---------- ------------ Backend developer with a passion for #scalability.
Report contribution
Obviously, it is good to align the API around the domain model to keep it as consistent as possible. However, the API should only return the data that is needed, and there should be a port between the REST API controller and the use case to avoid tightly coupling these two layers and to have the option to replace REST with gRPC.

Like
Adolfo Ranero Serrano

Information Security Officer | CISA & CRISC Certified by ISACA | 23k+ Followers
Report contribution
Definir bien los dominios es una tarea que no es sencilla. Requiere un conocimiento exhaustivo de la empresa y un claro entendimiento del Domain Driven Design. Hay que olvidar el enfoque tradicional CRUD de las APIs para acoplarlo, alinearlo, asimilarlo al modelo DDD: Dominios, entidades de dominio, agregados y objetos. Una buena cultura en BBDD relacionales ayuda bastante a crear este alineamiento entre DDD y API REST. De alguna manera el DDD es como una mega-base de datos relacional donde "mandan" los dominios y las APIs son los canales de comunicaciÃ³n entre estos "comandantes" dominios. Se orienta todo al dato y al evento. El dominio es un sÃºper conjunto que define uno o varios procesos de negocio.

Translated

Like

2 Use the right level of granularity

Another important aspect of DDD is to use the right level of granularity for your domain model. This means that you should identify the appropriate level of abstraction and detail for your domain concepts, and group them into aggregates that represent cohesive and consistent units of data and behavior. Aggregates are the basic building blocks of your domain model, and they have an aggregate root, which is the entity that controls the access and integrity of the aggregate.

When designing your RESTful API, you should use the right level of granularity for your API resources as well. This means that you should expose your aggregates as resources, and use the aggregate root as the primary identifier and entry point for your resource. You should also avoid exposing too much or too little detail about your aggregates, and provide only the relevant and necessary information for your API consumers. You should also avoid exposing the internal structure or state of your aggregates, and use hypermedia links to represent the relationships and transitions between your resources.

Add your perspective

3 Avoid CRUD-based APIs

A common mistake when designing RESTful APIs is to take a CRUD-based approach, which involves four basic operations: create, read, update, and delete. However, this approach can lead to several issues such as leaking implementation details and database schema to API consumers, creating an impedance mismatch between the domain model and API model, violating the encapsulation and consistency of aggregates, and reducing the expressiveness and clarity of the API. Instead of relying on CRUD operations, you should use a task-based approach where each API operation represents a meaningful task or action that consumers can perform on the resources. This way, you can align your API operations with domain services, commands and events to better convey the business intent and semantics of your API.

Add your perspective

4 Use versioning and evolution strategies

Dealing with changes and evolution over time is one of the unavoidable challenges of using RESTful APIs. As business domains and requirements evolve, so do domain models and APIs, which can affect existing API consumers who rely on the API contract and behavior. To manage changes and preserve the compatibility and stability of your API, you need to use versioning and evolution strategies. These strategies include URI versioning, where you include the version number in the resource path or query parameter; header versioning, where you include the version number in the request or response header; content negotiation, where you use the Accept or Content-Type header to specify the desired or supported format or representation of the resource; and HATEOAS, where you use hypermedia links to indicate the available or deprecated operations or resources. Each has its own advantages and disadvantages, but some general principles should be followed regardless of which method is chosen. These principles involve avoiding breaking changes as much as possible, communicating changes to API consumers in advance, supporting multiple versions for a reasonable period of time, and using semantic versioning to indicate the level and impact of the changes.

Add your perspective

Chris Vowell

Application Development Manager at The Greenbrier Companies
Report contribution
Along with versioning, you should document your API well. Implementing Swagger or other API definition and documentation standards will allow your consumers to understand your endpoints and capabilities along with changes between versions. They can even try out endpoints and explore expected inputs and outputs for your API.

Like

5 Hereâ€™s what else to consider

This is a space to share examples, stories, or insights that donâ€™t fit into any of the previous sections. What else would you like to add?

Add your perspective

Directory

What are some best practices for using RESTful APIs in DDD?

1

2

3

4

5

1 Align your API with your domain model

2 Use the right level of granularity

3 Avoid CRUD-based APIs

4 Use versioning and evolution strategies

5 Hereâ€™s what else to consider

Domain-Driven Design (DDD)

Rate this article

Thanks for your feedback

More articles on Domain-Driven Design (DDD)

More relevant reading