Capturing Intent in a REST API
In modern software development, there is a growing trend towards using intent-based approaches for building applications. Intent-based approaches focus on capturing the high-level intentions of users or systems and then automatically translating those intentions into actions or behaviors. At the same time our UX and UI are based on state representation approach. In this blog post, I will explore an anti-pattern between Domain Driven Design (DDD) and API design.
In an intent-based approach, the primary focus is on capturing the intent or desired outcome of a user or system. This intent is then used to drive the behavior of the application. By abstracting away the lower-level details and focusing on the intent, developers can build applications that are more flexible, adaptive, and easier to maintain. A common way within DDD to implement intent-based approach is using CQRS. The intent of the user is captured in Commands or Queries; Commands for change and Queries for request of current state.
For a long time APIs have been build using Representational State Transfer (REST). “The key abstraction in REST is a resource”, and as such the REST API designs discussions are mostly focused around the principles of naming the resources using structured path definitions. These discussions have been very useful as the results at least clearly indicate the targeted resource of the operation. Less focus is usually placed on the structure of the content of the communication. JSON blobs with information are being passed and producer/consumer use those parts that they require.
While this is working perfectly for responding to queries, this is not at all ideal for Commands. I’ve seen a lot of APIs where change requests happen through POST, PUT or PATCH operations containing the expected resulting state of the resource. By only focusing on the requested end state, we have to build logic to capture the intend behind the request.
A simple example is a request to change an address. In a REST API, it would be sent to a URL that identifies the resource and it will contain the new expected state, so only the new address. Within the domain we evaluate this request, conclude to create a command to update the address, but we don’t know the intent. Was the request sent, because the existing address was wrong? Or was there an actual change of address. Depending on the purpose of our application, this might have a big impact. If it’s only a correction, no further action might be required, but if it’s a new address, maybe a welcome message needs to be sent.
With this in mind, you might consider switching to a RPC based API approach, but then consider the query side that is actually benefitting from the state based approach. Which leads me to ponder: Is an hybrid mode the future?
