Last updated on 2024年6月14日

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.

本文章的要点总结

Task-based API design:

Ditch the standard create, read, update, and delete for a task-oriented approach. This aligns operations with domain services and events, enhancing the API's expressiveness and clarity to better reflect business intent.
Effective documentation:

Implement standards like Swagger for your API. This not only clarifies endpoints and their functions for users but also lets them interact with your API directly to understand inputs and outputs, smoothing out the learning curve.

本摘要由 AI 和以下专家提供支持

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.

添加您的观点

Luká? M.

Software developer ve spole?nosti Seznam.cz. ---------- ------------ Backend developer with a passion for #scalability.
举报内容
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.

已翻译

赞
Adolfo Ranero Serrano

Information Security Officer | CISA & CRISC Certified by ISACA | 23k+ Followers
举报内容
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.

已翻译

赞

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.

添加您的观点

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.

添加您的观点

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.

添加您的观点

Chris Vowell

Application Development Manager at The Greenbrier Companies
举报内容
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.

已翻译

赞

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?

添加您的观点

Domain-Driven Design (DDD)

+ 关注

给文章评分

我们借助人工智能创建了此文章。您认为这篇文章怎么样？

很棒不太好

举报此文章

查看全部

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)

给文章评分

感谢您的反馈

更多Domain-Driven Design (DDD)相关文章

更多相关阅读内容