Using the HTTP DELETE Method to Cancel the Current Action

Question

Background:

I provide a programming interface for people who want to place orders using my site.

They can use the GET and POST methods on /api/v1/orders to place an order and view a list of all the orders placed by them. They can also use the GET method on /api/v1/orders/<order_id> to view specific details of the same order.

You must specify the method of canceling the order, however, the records themselves must be saved.

I would like feedback from more experienced developers about whether this would be a reasonable solution:

a) implements the verb DELETE on /api/v1/current_orders/<order_id> , which will remove it from the list of "current" orders (marking it canceled). The disadvantage is that he will use another noun that may be misleading.

b) implements the verb DELETE on /api/v1/orders/<order_id> with the same functionality as in a). This is somewhat misleading, as the entity will not really be deleted, and the consumer should be aware of this.

c) we implement the POST verb on /api/v1/cancellations/<order_id> (or POST on /api/v1/cancellations with order_id in the JSON payload). This seems less ideal because the resource will not be created as a result of this request. However, the consequences of using this endpoint seem clearer.

d) ...?

Question:

I know that there is not always an “ideal” solution for designing endpoints for a REST API, but given the need for clarity and intuitiveness and with high attention to best practices , which option is “optimal” ?

Answer 1

What about the PATCH verb /api/v1/orders/<order_id> indicating that it is canceled?

HTTP PATCH : Allows partial modifications to an entity. While POST creates a new one and PUT replaces the existing one, PATCH simply updates the properties you send, leaving the rest in them.

You will only need to send something like { isCancelled:true} as an HTTP PATCH , then your code will update the object and take action on how to cancel any outstanding work.