Какие знаешь методы REST API?

Основные методы (HTTP-глаголы) REST API

REST API базируется на стандартных HTTP-методах (или «глаголах»), каждый из которых имеет строго определённую семантику и идемпотентность. Правильное применение этих методов — основа архитектурного стиля REST. Вот ключевые из них:

1. GET

Назначение: Получение (чтение) данных. Это идемпотентный и безопасный метод (не должен изменять состояние сервера).

Использование: Запрос ресурса или коллекции. Параметры передаются в URL (query string).

// Пример запроса: GET /api/users/123
public function getUser($id) {
    $user = User::find($id);
    return response()->json($user);
}

2. POST

Назначение: Создание нового ресурса. Неидемпотентный и небезопасный.

Использование: Передача данных для создания в теле запроса (обычно JSON или form-data).

// Пример запроса: POST /api/users
public function createUser(Request $request) {
    $user = User::create($request->all());
    return response()->json($user, 201); // Код 201 Created
}

3. PUT

Назначение: Полное обновление (замену) ресурса. Идемпотентный, но небезопасный.

Использование: Отправка полного представления ресурса для замены по указанному URI.

// Пример запроса: PUT /api/users/123
public function updateUser(Request $request, $id) {
    $user = User::findOrFail($id);
    $user->update($request->all()); // Заменяем все поля
    return response()->json($user);
}

4. PATCH

Назначение: Частичное обновление ресурса. В отличие от PUT, передаются только изменяемые поля. Теоретически неидемпотентный, но на практике часто реализуется как идемпотентный. Небезопасный.

Использование: Отправка набора изменений (например, в формате JSON Patch).

// Пример запроса: PATCH /api/users/123
public function patchUser(Request $request, $id) {
    $user = User::findOrFail($id);
    $user->fill($request->only(['name', 'email']))->save(); // Обновляем только указанные поля
    return response()->json($user);
}

5. DELETE

Назначение: Удаление ресурса. Идемпотентный и небезопасный.

Использование: Запрос на удаление ресурса по указанному URI.

// Пример запроса: DELETE /api/users/123
public function deleteUser($id) {
    User::destroy($id);
    return response()->json(null, 204); // Код 204 No Content
}

Дополнительные и менее распространённые методы

6. HEAD

Назначение: Аналогичен GET, но сервер возвращает только заголовки ответа без тела. Используется для проверки существования ресурса, валидации кэша (например, по заголовку ETag).

7. OPTIONS

Назначение: Описание возможностей (доступных методов) для целевого ресурса. Часто используется в механизме CORS (Cross-Origin Resource Sharing) для предварительных запросов (preflight). Сервер возвращает заголовок Allow: GET, POST, PUT.

Критические принципы использования

• Идемпотентность: Повторный идентичный запрос (кроме POST) должен приводить к тому же состоянию сервера. Это важно для механизмов повторной отправки при сетевых ошибках.
• Безопасность: Методы GET и HEAD не должны изменять состояние сервера. Они предназначены только для чтения.
• Семантика над действием: Метод указывает что сделать (GET, POST), а URI указывает с чем (/users, /orders/5/items).
• Коды состояния HTTP: Корректный REST API должен возвращать соответствующие HTTP-статусы:

    *   `200 OK` — успешный GET, PUT, PATCH.
    *   `201 Created` — успешное создание через POST.
    *   `204 No Content` — успешное DELETE или обновление без возвращаемого контента.
    *   `400 Bad Request` — ошибка в запросе клиента.
    *   `404 Not Found` — ресурс не найден.
    *   `405 Method Not Allowed` — метод не применим к данному ресурсу.

Пример RESTful маршрутизации для сущности "Статья"

// Маршруты в Laravel (пример)
Route::get('/articles', 'ArticleController@index');        // GET - список статей
Route::post('/articles', 'ArticleController@store');       // POST - создать статью
Route::get('/articles/{id}', 'ArticleController@show');    // GET - одна статья
Route::put('/articles/{id}', 'ArticleController@update');  // PUT - заменить статью
Route::patch('/articles/{id}', 'ArticleController@update'); // PATCH - частично обновить
Route::delete('/articles/{id}', 'ArticleController@destroy'); // DELETE - удалить

Понимание и строгое соблюдение семантики этих методов — это не просто формальность, а фундамент для построения предсказуемого, масштабируемого и надёжного API, которое легко понимают как клиентские разработчики, так и системы (кэши, прокси, поисковые роботы). Современные фреймворки (Laravel, Symfony) предоставляют удобные инструменты для реализации RESTful-маршрутов и контроллеров, следуя этим принципам.