rest - How to design a RESTful API that starts a process

Question

One of the resources in my API has an attribute that represents the status of this resource ("unchecked" --> "check initiated" --> "checked").

In order to transfer the resource from the status "unchecked" to the status "checked", it is necessary for a human being to carry out certain activities. Therefore, the server starts a process that involves human interaction. This process takes a while, but it should be possible to trigger it via the API.

My question is: What should the operation that starts this process look like? Is it a good idea to define a PATCH operation in whose body the status "check initiated" or "checked" is passed (which then leads to the start of the process on the server side)? Or would it be better to define a new resource that represents the process and that is activated with a POST request?

question from:https://stackoverflow.com/questions/65846140/how-to-design-a-restful-api-that-starts-a-process

Answer 1

How to design a RESTful API that starts a process

How would you do it with a web site?

You'd load up the "home page", then follow a bunch of links until you arrived at the "starts a process" form, and you would perhaps supply some inputs to the form, and then "submit" it. At that point, your browser would apply the standardized form processing rules to copy your inputs (and hidden/defaulted values, and some metadata, etc) into an application/x-www-form-urlencoded document which would then become the payload of a POST request (on the assumption that "starts a process" is not effectively read-only).

The user, typically, doesn't care what the target uri is (did you check where the stack overflow form was going to send your question before you submitted it?), and the browser doesn't care either - it just copies the value that was provided in the form metadata.

Which allows you, the api designer, much freedom in what the uri should be. You might, for instance, choose the uri that produces the cache invalidation that you want.

---

Yes, it is also fine to use a remote authoring idiom instead of a form submission idiom. You GET a copied representation of a resource, make local edits to it, and then request that the server update its copy of that resource. PUT has some nice advantages, but if the representation is much larger than the http headers and the change you are making is small, then you might prefer the tradeoffs you get by sending a PATCH instead.

---

But my question is not which HTTP verb should be used, but whether it is appropriate to change the status in the request, although the purpose of the request is actually to start the process

If I'm understanding you correctly: sure, that's fine.

For example, imagine a kitchen oven with a "REST API" that allows us to talk to it. The oven resource (loosely, the document that describes the oven) might include a field for current temperature, and another field for target temperature.

If we want to bake potatoes, we might send to the REST API a message that says "change the oven document so that the target temperature is 425F". A side effect of accepting that change would be the server actually lighting the gas in the oven to start it warming.

See Webber 2011