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 (RPC)

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.

Example

An API has a Message resource and it provides the standard CRUD methods like:

GET    https://api.island.is/v1/messages
GET    https://api.island.is/v1/messages/:messageId
POST   https://api.island.is/v1/messages
PUT    https://api.island.is/v1/messages/:messageId
DELETE https://api.island.is/v1/messages/:messageId

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:

POST   https://api.island.is/v1/messages/:messageId/archive
POST   https://api.island.is/v1/messages/:messageId/unarchive

The batch archiving is provided by

POST   https://api.island.is/v1/messages/archive
POST   https://api.island.is/v1/messages/unarchive

Note: The POST method accepts a list of message Ids in the request body.