Task oriented user interface and Rest application server API

Question

I am designing a system where the user interface will be constructed using a mixture of task oriented UI and CRUD UI. This way we want to be able to have an optimal user experience for different user roles.

The client application uses REST/JSON to communicate with the application server.

For the CRUD part the REST API part is mostly straight foreward. But designing the API for the task oriented actions in our application is a little bit more difficult.

How would one go about designing a REST API that makes a distinction between two different actions on a resource that both actually just update the data?

As an example - The user can change a person's address for the following reasons:

1. The address contains a fault, e.g. the street's name is spelled wrong.
2. The person has moved to a different address

Both reasons result in the same end situation; the data has changed. But in the REST API there should somehow be a difference to be able to react differently.

Answer 1

Generally a REST resource will be a noun. However, it is also legitimate for the resource to be a process or process step. Thus for the example you've given, I might do this:

• Correcting a typo in an address:

PUT /resource/customer/123/address

• Customer moved, execute a change-of-address:

POST /resource/customer/123/changeOfAddress

In the latter case, the HTTP body would presumably contain additional information such as "effective date". Also, the content-location header returned from the above POST likely would contain the URI to resource that shows the old address, the new address, and when the transition occurred.

Thus the changeOfAddress is nominally a "process" but it is practically a noun unto itself; from a modelling POV, it is a first-class citizen.