api-guidelines
api-guidelines copied to clipboard
microsoft
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 } ]
}
On the whole, we've been following the OData action convention which is just to use a regular '/' delimiter. This does leave open the possibility of ambiguity, but in practice items have something like a Guid as an identifier in many services, making it not an issue. For ARM services where human-centric identifiers are used, I don't know what we're doing, although in general, I find that pattern to be a bit crazy.
Service health (and other metadata) can be consider simply a read-only resource:
GET https://api.contoso.com/v1.0/service/health
