What is the best way to design a REST API?

Question

RESTful API

Greetings!

When designing the API, I encountered a misunderstanding of the idempotency of methods in the context of business logic. Please help.

Suppose there is a service for turning on, turning off and restarting computers, and each operation here is asynchronous (so that the client does not wait for a response); then it is logical to have these resources and methods for them:

• POST /api/computers/runs/operations - start the computer (in response - an asynchronous operation with an identifier)
  
• GET /api/computers/runs/operations/{operation:uuid} - get information about the run operation
  
• GET /api/computers/runs/operations - listing all operations
  
• POST /api/computers/shutdowns/operations - shutting down the computer (in response - an asynchronous operation with an identifier)
  
• ... about the same set of methods as above, but only for reloading
  

Now, according to the business logic, the question arises of canceling the launch operation, and here two options come to mind (actually, I have difficulty in choosing one of the two to make it the most logical):

• DELETE /api/computers/runs/operations/{operation:uuid}
  
• POST /api/computers/runs/operations/{operation:uuid}/cancels
  

It is important to consider that I do not want to delete the operation object itself from the database: I just want to change its state to operation.canceled=True, for example; and the first method in this case is more simple and logical. And I also believe that implementation details (removing an entry or changing the state of this entry) should not be fundamental when designing resources and methods for them.

What do you think?

Answer 1

Some painfully strange ways.
But in general, yes - everything should be POST-ami here, since it is impossible to cancel the canceled operation.
Well, IMHO, such logic is poorly placed on the rest, so it’s quite ok to do
Create a new task
POST /api/machines/{machineId}/jobs
And indicate in the body that it is start/stop/reset
Cancel
POST /api/machines /{machineId}/jsobs/{jobId}/cancel
Not DELETE, because by semantics the resource should disappear after DELETE.
To get a list
GET /api/machines/{machineId}/jobs
To get information on a specific task
GET /api/machines/{machineId}/jobs/{jobId}
If you need to get a list of tasks to include:
GET /api/machines/{ machineId}/jobs?type=start
By naming, kmk, the word "machine" and "job" looks better, and not "computer" and "operation"