Question: request pattern for non CRUD operations

While it's easy to design API around the concept of Create, Read, Update, Delete, often services need to support actions which don't map well to CRUD nor to HTTP methods.

Some examples:

• Creating a resource using a template, providing data for template placeholders
• Searching resources with a complex query that doesn't fit in the URL
• Executing a special operation on a resource, e.g. backup
• Checking a service health
• Input validation
• I'd include here batch operations, although I see a branch in the repository about this topic

The current guidelines have only a brief reference to the backup scenario:

POST https://api.contoso.com/v1.0/databases/db1?backup HTTP/1.1

Do the guidelines cover this topic or do you plan to add a section?

I've been looking at the ?action pattern used by Amazon S3 multi-object delete API (https://docs.aws.amazon.com/AmazonS3/latest/API/multiobjectdeleteapi.html), and the :customVerb pattern used by Google Cloud API (https://cloud.google.com/apis/design/custom_methods). And since it seems mostly a matter of choosing a special char, "!" is also often used to specify commands.

From an implementation perspective (not just ASP.NET) though, any character chosen can lead to unexpected behavior. For instance HTTPVERB /items?unknownAction and HTTPVERB /items!unknownAction and HTTPVERB /items:unknownAction can be routed to the default verb implementation (e.g. POST /items?validate routed to POST /items) resulting, for instance, in a creation instead of a validation.

Other guidelines and recommendations adopt custom endpoints, e.g.

• http://api.contoso.com/v1.0/actions
• http://api.contoso.com/v1.0/databasesActions/backup
• http://api.contoso.com/v1.0/databasesBackup

which deviates from the idea of having one endpoint per resource.

Some examples below, about using a special char in the URL.

Executing an operation on a resource, e.g. backup:

POST https://api.contoso.com/v1.0/databases/db1?backup
or
POST https://api.contoso.com/v1.0/databases/db1:backup
or
POST https://api.contoso.com/v1.0/databases/db1!backup

Creating a resource using a template, providing data for template placeholders:

POST https://api.contoso.com/v1.0/databases?fromTemplate

{
  .. template id and data ..
}

Searching resources with a complex query that doesn't fit in the URL:

POST https://api.contoso.com/v1.0/items!search

{
  .. complex search parameters ..
}

Checking a service health:

POST https://api.contoso.com/v1.0/?status

Input validation:

POST https://api.contoso.com/v1.0/items:validate

{
  .. complete item representation ..
}

Batch delete:

PUT https://api.contoso.com/v1.0/items?deleteBatch

{
    "Items": [ { id }, { id }, { id } ]
}

Review the current API guidelines, especially the brief backup example, and inspect the repository branch about batch operations mentioned in the issue. Done would mean reaching a documented decision on whether and how non-CRUD operations should be covered, including the routing patterns and examples to recommend.