REST API are often designed to “manipulate data”. In fine, that what every API do: send data to a server and get some return data back. In fact, there are different ways to do that, and every approach will have a different impact on what the API client should know/do and the facility of achieving its goals.

Let’s consider an example, an Issues management system. It deals with issues creation, and life-cycle management (confirm, assign, cancel, close).

Design 1: Data oriented design

Let’s consider an issue located at https://seq.datanarchy.com/issues/1 .

Performing a GET on that returns a json like this:

{
  "uid": "1",
  "description": "some random description",
  "title": "A new Issue",
  "status": {
    "value": "CREATED",
    "date": "2020-02-08T23:12:27Z"
  }
}

At this point, there is no relevant problem. Let’s consider the next step: accept and confirm the issue. In a data oriented design, we will do the following:

PUT /issues/1
Host: https://seq.datanarchy.com
Content-Type: application/json

{
	"uid": "1",
  "description": "some random description",
  "title": "A new Issue",
  "status": {
    "value": "CONFIRMED"
  }
}

The same approach could be done by a PATCH call with only the status.

What is the problem here? It works, right? Yes, but confirming an issue is more than updating a single data of the issue:

• May be the action can be performed by a specific user role, while updating the description is open to the issue creator.
• May be there is processes launched (alerts, notifications) based on the confirmation of the severity of the issue, while the other data doesn’t trigger this behavior
• …

As we can see, this is not only about updating data. It’s about behavior of the system, guided by business rules and based on the state of the elements.

Design 2: Use case (or Domain) oriented design

The second approach will focus on business domain: We do not update the status of the issue to “CONFIRMED”, we “confirm the issue” and as consequence the status will update.

• But before updating the status, we will check the current status and if we can confirm an issue having that status;
• We will check the authorizations of the current user to check if he has the right to do that action;
• We will check the criticality of the issue and determine it’s priority;
• etc…

Then, the HTTP request should not update the /issues/1 resource, but rather creates a “confirmation command of the issue 1”, which can be reflected by a /issues/1/confirmation-command.

POST /issues/1/confirmation-command
Host: https://seq.datanarchy.com
Content-Type: application/json

In this second design, we can keep the PUT action on the /issues/{uid} to update value attributes : the description and the title of the issue, as they do not influence the behavior of the issue.

The advantages of this approach are:

• Each of PUT /issues/1 and POST /issues/1/confirmation-command handle only one action (Single Responsibility of the action)
• The design more understandable and simple to implement and debug
• The semantics of the actions are more business oriented

In the next post, we will see how to bring this design to the next level with hypermedia controls.