Урок 13: RESTful API в Laravel

В 13-ом уроке мы изучимв RESTful API. Если вы дошли до этого урока, значит, уже освоили основы Laravel и готовы научиться создавать API это мощный инструмент для взаимодействия между приложениями. В этом уроке я подробно расскажу о принципах REST, создании API-роутов, форматировании JSON-ответов и документировании API в Postman. Мы разберем все шаги на примерах, а в конце вас ждут практические задачи для закрепления материала.

Основы REST API

REST (Representational State Transfer) это архитектурный стиль, который определяет правила создания веб-сервисов. Его главная идея, это использовать стандартные HTTP-методы (GET, POST, PUT, DELETE) для взаимодействия с ресурсами. Каждый ресурс (например, статья, пользователь или товар) имеет уникальный URL, а операции с ним выполняются через запросы.

Принципы REST:

1. Единообразие интерфейса
   Каждый URL представляет ресурс, а HTTP-метод это действие с ним.
2. Отсутствие состояния (Stateless)
   Сервер не хранит информацию о предыдущих запросах клиента. Каждый запрос самодостаточен.
3. Кэширование
   Ответы сервера могут кэшироваться для повышения производительности.
4. Слоистая архитектура
   Клиент не знает, с каким слоем сервера взаимодействует.

Примеры HTTP-методов для REST:

• GET /api/posts — получить список статей.
• POST /api/posts — создать новую статью.
• GET /api/posts/1 — получить статью с ID=1.
• PUT /api/posts/1 — обновить статью с ID=1.
• DELETE /api/posts/1 — удалить статью с ID=1.

Создание API-роутов (api.php)

В Laravel API-роуты определяются в файле routes/api.php. По умолчанию все URL здесь автоматически добавляют префикс /api. Давайте создадим простой API для работы с блогом.

Пример 1: Базовые роуты для CRUD

// routes/api.php
use App\Http\Controllers\PostController;

Route::get('/posts', [PostController::class, 'index']);
Route::post('/posts', [PostController::class, 'store']);
Route::get('/posts/{id}', [PostController::class, 'show']);
Route::put('/posts/{id}', [PostController::class, 'update']);
Route::delete('/posts/{id}', [PostController::class, 'destroy']);

Пример 2: Использование Route::apiResource

Laravel позволяет автоматизировать создание CRUD-роутов:

Route::apiResource('posts', PostController::class);

Эта строка создаст те же 5 роутов, что и в первом примере.

Форматирование JSON-ответов

Правильное форматирование ответов важно для удобства клиентов API. В Laravel есть несколько подходов.

Способ 1: Возврат массива

Контроллер может вернуть массив, который Laravel автоматически преобразует в JSON:

public function index()
{
    return [
        'data' => Post::all(),
        'status' => 'success'
    ];
}

Результат:

{
    "data": [{"id": 1, "title": "..."}, ...],
    "status": "success"
}

Способ 2: Использование Eloquent Resources

Ресурсы позволяют контролировать формат данных. Создадим ресурс для модели Post:

php artisan make:resource PostResource

В файле app/Http/Resources/PostResource.php:

public function toArray($request)
{
    return [
        'id' => $this->id,
        'title' => $this->title,
        'created_at' => $this->created_at->format('d.m.Y'),
    ];
}

Использование в контроллере:

public function show(Post $post)
{
    return new PostResource($post);
}

Документирование API в Postman

Postman популярный инструмент для тестирования и документирования API. Давайте создадим коллекцию для нашего блога.

Шаги:

1. Создайте коллекцию «Блог API».
2. Добавьте запросы для каждого эндпоинта:
   • GET /api/posts
   • POST /api/posts (в теле запроса укажите JSON с полями title и content).
3. Добавьте примеры ответов для успешных и ошибочных сценариев.
4. Экспортируйте коллекцию в формате JSON, чтобы делиться с командой.

Пример документации для POST /posts:

**Описание**: Создание новой статьи.  
**Параметры тела (JSON)**:
```json
{
    "title": "Название статьи",
    "content": "Текст статьи"
}

Успешный ответ (201 Created):

{
    "data": {
        "id": 1,
        "title": "Название статьи",
        "created_at": "01.01.2024"
    },
    "status": "success"
}

Практические задачи

Задача 1: Создание API для пользователей

1. Сгенерируйте модель, миграцию и контроллер для User.
2. Создайте API-роуты для CRUD операций.
3. Реализуйте форматирование ответов через ресурсы.

Задача 2: Добавление пагинации

Измените метод index в PostController, чтобы он возвращал по 10 записей на страницу:

public function index()
{
    return PostResource::collection(Post::paginate(10));
}

Итоги 13-го урока

Теперь вы умеете создавать RESTful API в Laravel, от проектирования роутов до документирования в Postman. Практикуйтесь с форматами ответов и не забывайте о валидации данных, но об этом мы поговорим в следующих уроках.

Готовы двигаться дальше? Полный курс по Laravel для начинающих