# Methods

Methods are operations a client can take on resources. Follow [resource-oriented design](/technical-overview/api-design-guide/resource-oriented-design.md) 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](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete)). 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/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](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.devland.is/technical-overview/api-design-guide/methods.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.