REST API design for non-CRUD actions, e.g. save, deploy, execute code

I think you are looking for controllers, according to REST API design RuleBook:

A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs. Like a traditional web application’s use of HTML forms, a REST API relies on controller resources to perform application-specific actions that cannot be logically mapped to one of the standard methods (create, retrieve, update, and delete, also known as CRUD). Controller names typically appear as the last segment in a URI path, with no child resources to follow them in the hierarchy. The example below shows a controller resource that allows a client to resend an alert to a user: POST /alerts/245743/resend

and also:

POST should be used to create a new resource within a collection and execute controllers.

Could you please share your opinion how best we can design the APIs for these actions?

Create/Update/Delete information resources, and as a side effect of that, do work behind the API.

So think documents.

One very good example: In RESTful Casuistry, Tim Bray asked about an api to shut down a machine. Seth Ladd's response, in particular, is important to read

Fundamentally, REST is a bureaucracy that solves problems with paperwork. If you want to get anything done, you submit the right form; which becomes an information resource describing what you want done.

PUT /deploymentRequests/abcde

Please find the artifacts from build 12345 and deploy that artifact
to machine 67890

201 Created

The request is just a document, in exactly the same way a sticky note on your desk asking you to address some task is a document.

As far as REST is concerned, the spelling of the URI absolutely does not matter; but from the point of view of a human readable naming convention, start from the fact that the resource is the document -- not the side effect that you want the document to have.

So, for example, it's totally normal and compliant with REST that the document that describes the current state of a thing and the document that describes changes you want to make to a thing are different documents with different identifiers.

Tags:

Rest