Search…
Methods
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
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
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.

Methods mapping to HTTP verbs

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)
LIST
GET
GET
GET
CREATE
POST
UPDATE
PATCH/PUT
DELETE
DELETE
Custom
POST (usually)

Custom methods

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 nounify the action and make it a sub-resource.

Example

An API has a Message resource and it provides the standard CRUD methods like:
1
GET https://api.island.is/v1/messages
2
GET https://api.island.is/v1/messages/:messageId
3
POST https://api.island.is/v1/messages
4
PUT https://api.island.is/v1/messages/:messageId
5
DELETE https://api.island.is/v1/messages/:messageId
Copied!
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:
1
POST https://api.island.is/v1/messages/:messageId/archives
2
DELETE https://api.island.is/v1/messages/:messageId/archives
Copied!
The batch archiving is provided by
1
POST https://api.island.is/v1/messages/archives
2
DELETE https://api.island.is/v1/messages/archives
Copied!
Note: The POST method accepts a list of message Ids in the request body.
Last modified 10mo ago