Как правильно организовать API в Laravel: лучшие практики и примеры

Расширенные примеры реализации API на Laravel

Пример 1: Полный REST API для статей с пагинацией, фильтрацией и вложенными ресурсами

Допустим, необходимо предоставить эндпоинты для статей с возможностью фильтрации по категории, сортировки по дате и включения автора. Используем пакет spatie/laravel-query-builder для удобной фильтрации и сортировки.

// Установка пакета
composer require spatie/laravel-query-builder

// ArticleController
use Spatie\QueryBuilder\QueryBuilder;

public function index(Request $request)
{
    $articles = QueryBuilder::for(Article::class)
        ->allowedFilters(['title', 'category_id', 'created_at'])
        ->allowedSorts('created_at', 'title')
        ->allowedIncludes('author', 'comments')
        ->paginate($request->input('per_page', 15));

    return ArticleResource::collection($articles);
}

// Пример запроса
GET /api/v1/articles?filter[category_id]=2&sort=-created_at&include=author&per_page=5

// ArticleResource с поддержкой included
class ArticleResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'body' => $this->body,
            'created_at' => $this->created_at,
            'category' => new CategoryResource($this->whenLoaded('category')),
            'author' => new UserResource($this->whenLoaded('author')),
            'comments_count' => $this->whenCounted('comments'),
        ];
    }
}

// Результат для запроса выше (сокращён)
{
  "data": [
    {
      "id": 10,
      "title": "API Best Practices",
      "body": "Lorem ipsum...",
      "created_at": "2025-03-21T12:00:00.000000Z",
      "author": {
        "id": 1,
        "name": "Иван Петров"
      },
      "comments_count": 3
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 5,
    "total": 20
  },
  "links": {
    "first": "http://example.com/api/v1/articles?page=1",
    "last": "http://example.com/api/v1/articles?page=4",
    "prev": null,
    "next": "http://example.com/api/v1/articles?page=2"
  }
}

Пример 2: Обработка ошибок и кастомные ответы

Для единообразного формата ошибок используется исключения Laravel и собственные классы ответов.

// app/Exceptions/Handler.php (Laravel 11)
public function register(): void
{
    $this->reportable(function (Throwable $e) {
        //
    });

    $this->renderable(function (ValidationException $e, $request) {
        if ($request->expectsJson()) {
            return response()->json([
                'message' => 'Ошибка валидации',
                'errors' => $e->errors(),
            ], 422);
        }
    });

    $this->renderable(function (ModelNotFoundException $e, $request) {
        if ($request->expectsJson()) {
            return response()->json([
                'message' => 'Ресурс не найден',
            ], 404);
        }
    });
}

// Использование в контроллере
use App\Exceptions\CustomApiException;

public function show($id)
{
    $article = Article::find($id);
    if (!$article) {
        throw new CustomApiException('Статья не найдена', 404);
    }
    return new ArticleResource($article);
}

Пример 3: Генерация API-токенов через Sanctum с ограничением способностей (abilities)

// В контроллере аутентификации
public function login(Request $request)
{
    $credentials = $request->validate([
        'email' => 'required|email',
        'password' => 'required',
    ]);

    if (!Auth::attempt($credentials)) {
        return response()->json(['message' => 'Неверные учётные данные'], 401);
    }

    $user = Auth::user();
    $token = $user->createToken('api-token', ['articles:read', 'articles:write'])->plainTextToken;

    return response()->json([
        'token' => $token,
        'abilities' => ['articles:read', 'articles:write'],
    ]);
}

// Использование в маршрутах
Route::middleware('auth:sanctum', 'abilities:articles:read')->get('/articles', [ArticleController::class, 'index']);
Route::middleware('auth:sanctum', 'abilities:articles:write')->post('/articles', [ArticleController::class, 'store']);

Пример 4: Тестирование API с использованием Laravel Dusk или PHPUnit

// tests/Feature/Api/ArticleTest.php
<?php

namespace Tests\Feature\Api;

use Tests\TestCase;
use App\Models\Article;
use App\Models\User;
use Laravel\Sanctum\Sanctum;

class ArticleTest extends TestCase
{
    public function test_can_list_articles()
    {
        Article::factory()->count(3)->create();

        $response = $this->getJson('/api/v1/articles');

        $response->assertStatus(200);
        $response->assertJsonCount(3, 'data');
    }

    public function test_unauthenticated_user_cannot_create_article()
    {
        $response = $this->postJson('/api/v1/articles', [
            'title' => 'Test',
            'body' => 'Content',
        ]);

        $response->assertStatus(401);
    }

    public function test_authenticated_user_can_create_article()
    {
        Sanctum::actingAs(
            User::factory()->create(),
            ['articles:write']
        );

        $response = $this->postJson('/api/v1/articles', [
            'title' => 'New Article',
            'body' => 'This is the body of the article',
        ]);

        $response->assertStatus(201);
        $response->assertJson([
            'data' => [
                'title' => 'New Article',
            ]
        ]);
    }
}

// Результат запуска php artisan test
PASS  Tests\Feature\Api\ArticleTest
✓ can list articles
✓ unauthenticated user cannot create article
✓ authenticated user can create article
Tests: 3 passed

Пример 5: Использование Rate Limiting для API

// В AppServiceProvider или RouteServiceProvider
RateLimiter::for('api', function (Request $request) {
    return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
});

// В routes/api.php
Route::middleware('throttle:api')->group(function () {
    Route::apiResource('articles', ArticleController::class);
});

// При превышении лимита клиент получает ответ
{
  "message": "Too Many Attempts.",
  "retry_after": 30
}