Какие есть методы в REST API?

Методы HTTP в REST API

В RESTful архитектуре методы HTTP (или HTTP-глаголы) являются ключевым механизмом для определения типа операции, которую клиент хочет выполнить над ресурсом, идентифицируемым URI. Эти методы соответствуют CRUD операциям (Create, Read, Update, Delete) и должны использоваться согласно их семантике, определённой в спецификациях RFC 7231 и RFC 5789. Это обеспечивает единообразие, предсказуемость и корректную работу кэширования, безопасности и идемпотентности.

Основные (базовые) методы

1. GET

    *   **Назначение:** Получение (чтение) представления ресурса или коллекции ресурсов.
    *   **Свойства:** **Идемпотентный**, **безопасный** (не изменяет состояние ресурса на сервере).
    *   **Типичный статус ответа:** `200 OK` (успех), `404 Not Found` (ресурс не найден), `400 Bad Request`.
    *   **Пример использования:** Получение списка пользователей или конкретного пользователя.

```http
GET /api/users HTTP/1.1
GET /api/users/123 HTTP/1.1
```

2. POST

    *   **Назначение:** Создание нового ресурса. Часто используется для операций, не вписывающихся в CRUD (например, запуск процесса, поиск с сложными критериями).
    *   **Свойства:** **Неидемпотентный**, **небезопасный**.
    *   **Типичный статус ответа:** `201 Created` (с заголовком `Location`), `400 Bad Request`, `409 Conflict`.
    *   **Пример использования:** Создание нового заказа или регистрация пользователя.

```http
POST /api/users HTTP/1.1
Content-Type: application/json

{"name": "Алексей", "email": "alex@example.com"}
```

3. PUT

    *   **Назначение:** Полное обновление ресурса. Клиент отправляет полное представление ресурса, заменяя существующее. Также может использоваться для создания ресурса, если его идентификатор известен клиенту.
    *   **Свойства:** **Идемпотентный**, **небезопасный**.
    *   **Типичный статус ответа:** `200 OK` или `204 No Content` (успешное обновление), `201 Created` (успешное создание).
    *   **Пример использования:** Обновление всей информации о пользователе с ID 123.

```http
PUT /api/users/123 HTTP/1.1
Content-Type: application/json

{"name": "Обновлённый Алексей", "email": "updated@example.com"}
```

4. DELETE

    *   **Назначение:** Удаление указанного ресурса.
    *   **Свойства:** **Идемпотентный**, **небезопасный**.
    *   **Типичный статус ответа:** `204 No Content` (успешно удалён), `202 Accepted` (удаление принято в обработку), `404 Not Found`.
    *   **Пример использования:** Удаление статьи.

```http
DELETE /api/articles/456 HTTP/1.1
```

Дополнительные (расширенные) методы

1. PATCH

    *   **Назначение:** **Частичное обновление** ресурса. Клиент отправляет только изменяемые поля, а не весь ресурс (например, в формате JSON Patch или JSON Merge Patch).
    *   **Свойства:** **Неидемпотентный** (хотя может быть реализован идемпотентно, например, с JSON Patch), **небезопасный**.
    *   **Типичный статус ответа:** `200 OK`, `204 No Content`, `400 Bad Request`.
    *   **Пример использования:** Изменение только статуса заказа.

```http
PATCH /api/orders/789 HTTP/1.1
Content-Type: application/json-patch+json

[{"op": "replace", "path": "/status", "value": "shipped"}]
```

6. HEAD

    *   **Назначение:** Аналогичен GET, но сервер возвращает только заголовки ответа **без тела**. Используется для проверки существования ресурса, получения метаданных (например, `Content-Type`, `Content-Length`) или проверки валидности кэша (`Last-Modified`, `ETag`).
    *   **Свойства:** **Идемпотентный**, **безопасный**.
    *   **Пример использования:** Проверка, изменился ли файл с момента последнего запроса.

```http
HEAD /api/documents/report.pdf HTTP/1.1
If-None-Match: "abc123"
```

7. OPTIONS

    *   **Назначение:** Получение информации о **возможностях** сервера или ресурса: какие HTTP-методы поддерживаются, какие заголовки можно использовать. Критически важен для **CORS** (Cross-Origin Resource Sharing).
    *   **Свойства:** **Идемпотентный**, **безопасный**.
    *   **Типичный ответ:** Заголовок `Allow: GET, POST, PUT, DELETE` и другие CORS-заголовки (`Access-Control-Allow-Methods`).

```http
OPTIONS /api/users HTTP/1.1
```

Ключевые принципы выбора метода

• Идемпотентность: Повторный идентичный запрос (GET, PUT, DELETE, HEAD, OPTIONS) не должен оказывать дополнительного эффекта сверх первого. Это важно для автоматических повторов запросов при сетевых сбоях.
• Безопасность: Методы GET, HEAD, OPTIONS не должны изменять состояние сервера.
• Семантика над синтаксикой: Важно, что делает метод, а не как он называется. POST на /api/users создаёт пользователя, а PUT на /api/users/123 — обновляет или создаёт конкретного.
• Соответствие CRUD: Старайтесь сопоставлять POST (Create), GET (Read), PUT/PATCH (Update), DELETE (Delete).

В современной iOS-разработке при работе с REST API мы используем URLSession или фреймворки вроде Alamofire. Понимание различий между методами, особенно PUT и PATCH, или нюансов идемпотентности, напрямую влияет на корректность реализации сетевого слоя, обработку ошибок и повторных попыток запросов, что критично для пользовательского опыта в мобильных приложениях, работающих в условиях нестабильного сетевого соединения.