Methods
Last updated
Last updated
Methods are operations a client can take on resources. Follow resource-oriented design when developing methods for APIs. Emphasize resources (data model) over the methods performed on the resources (functionality). A typical resource-oriented API exposes a large number of resources with a small number of methods.
Most API services support the following 5 operations: LIST, GET, CREATE, UPDATE, and DELETE on all resources, also known as the standard methods (CRUD). Create custom methods to provide a means to express arbitrary actions that are difficult to model using only the standard methods.
A photo album service, for example, may provide the following methods:
| Method | Resource | |
|---|---|---|
For obvious reasons, operations CREATE and LIST always work on a resource collection, and GET, UPDATE and DELETE on a single resource. Note: You should never define a method with no associated resource.
In HTTP RESTful API services, each method must be mapped to an HTTP verb (HTTP request methods).
The following table specifies the mappings between standard and custom methods and HTTP verbs:
| Method | HTTP Request Method (Verb) |
|---|---|
APIs should prefer standard methods over custom methods. However, in the real world there is often a need to provide custom methods. A custom method is an action that does not cleanly map to any of the standard methods. The way to add custom methods to your API is to use POST and add the verb of the action as a sub-resource.
An API has a Message resource and it provides the standard CRUD methods like:
Then there is a requirement to provide a functionality to be able to archive and unarchive a single message and a batch of messages. The archiving and unarchiving of a single message is then provided by:
The batch archiving is provided by
Note: The POST method accepts a list of message Ids in the request body.
CREATE Creates a user
//my-service.island.is/v1/users
a collection of User resources
GET Gets a user
//my-service.island.is/v1/users/:userId
a single User resource
UPDATE Updates a user
//my-service.island.is/v1/users/:userId
a single User resource
LIST Lists photos of a user
//my-service.island.is/v1/users/:userId/photos
a collection of Photos resources
DELETE Deletes a photo
//my-service.island.is/v1/users/:userId/photos/:photoId
a single Photo resource
LIST
GET
GET
GET
CREATE
POST
UPDATE
PATCH/PUT
DELETE
DELETE
Custom
POST (usually)