Версия 1 REST API на PHP: от проектирования до реализации

Расширенные примеры и нестандартные ситуации

Дополнительные сценарии для API v1, которые помогут избежать проблем в продакшене.

Версионирование через заголовок Accept

Как реализовать версионирование API без изменения URL?

Вместо префикса /v1 можно использовать заголовок Accept с указанием версии. Пример с Slim:

<?php
$app->add(function (Request $request, RequestHandler $handler) {
    $accept = $request->getHeaderLine('Accept');
    if (strpos($accept, 'application/vnd.api.v1+json') !== false) {
        $request = $request->withAttribute('api_version', 'v1');
    }
    return $handler->handle($request);
});

$app->get('/users', function (Request $request, Response $response) {
    $version = $request->getAttribute('api_version', 'v1');
    $data = [];
    if ($version === 'v1') {
        $data = ['id' => 1, 'name' => 'Иван'];
    }
    $payload = json_encode($data, JSON_UNESCAPED_UNICODE);
    $response->getBody()->write($payload);
    return $response->withHeader('Content-Type', 'application/vnd.api.v1+json');
});

Результат при запросе с заголовком Accept: application/vnd.api.v1+json:

{"id":1,"name":"Иван"}

Пагинация и фильтрация

Как добавить постраничный вывод списка пользователей API v1?

Ресурс /v1/users?page=2&limit=10. Пример на Slim с ручной обработкой:

<?php
$app->get('/v1/users', function (Request $request, Response $response) {
    $params = $request->getQueryParams();
    $page = max(1, (int)($params['page'] ?? 1));
    $limit = min(100, max(1, (int)($params['limit'] ?? 10)));
    $offset = ($page - 1) * $limit;
    
    // Предположим, есть функция getUsers() возвращающая массив
    $users = getUsers($offset, $limit);
    $total = getTotalUsers();
    
    $result = [
        'data' => $users,
        'meta' => [
            'page' => $page,
            'limit' => $limit,
            'total' => $total,
            'pages' => ceil($total / $limit),
        ]
    ];
    $payload = json_encode($result, JSON_UNESCAPED_UNICODE);
    $response->getBody()->write($payload);
    return $response->withHeader('Content-Type', 'application/json');
});

Запрос GET /v1/users?page=1&limit=2 вернёт:

{"data":[{"id":1,"name":"Иван"},{"id":2,"name":"Мария"}],"meta":{"page":1,"limit":2,"total":10,"pages":5}}

Кастомные исключения и обработка ошибок

Как вернуть стандартизированный JSON при ошибке (400, 404, 500)?

Глобальная обработка исключений в Slim через интерфейс ErrorHandlerInterface:

<?php
use Slim\Exception\HttpNotFoundException;
use Slim\Exception\HttpMethodNotAllowedException;

$app->addErrorMiddleware(true, true, true)
    ->setDefaultErrorHandler(function (
        ServerRequestInterface $request,
        Throwable $exception,
        bool $displayErrorDetails,
        bool $logErrors,
        bool $logErrorDetails
    ) use ($app) {
        $statusCode = 500;
        if ($exception instanceof HttpNotFoundException) {
            $statusCode = 404;
        } elseif ($exception instanceof HttpMethodNotAllowedException) {
            $statusCode = 405;
        }
        $response = $app->getResponseFactory()->createResponse($statusCode);
        $payload = json_encode([
            'error' => [
                'code' => $statusCode,
                'message' => $exception->getMessage()
            ]
        ], JSON_UNESCAPED_UNICODE);
        $response->getBody()->write($payload);
        return $response->withHeader('Content-Type', 'application/json');
    });

Результат при запросе несуществующего маршрута:

{"error":{"code":404,"message":"Not found."}}

Валидация входящих данных

Как проверить поля при создании пользователя (POST /v1/users)?

Используйте стороннюю библиотеку respect/validation с Slim или встроенные средства Laravel. Пример на Slim:

<?php
use Respect\Validation\Validator as v;

$app->post('/v1/users', function (Request $request, Response $response) {
    $data = $request->getParsedBody();
    $nameValidator = v::stringType()->notEmpty()->length(1, 100);
    $emailValidator = v::email();
    
    $errors = [];
    if (!$nameValidator->validate($data['name'] ?? '')) {
        $errors['name'] = 'Имя должно быть строкой от 1 до 100 символов';
    }
    if (!$emailValidator->validate($data['email'] ?? '')) {
        $errors['email'] = 'Некорректный email';
    }
    
    if (!empty($errors)) {
        $payload = json_encode(['errors' => $errors], JSON_UNESCAPED_UNICODE);
        $response->getBody()->write($payload);
        return $response->withHeader('Content-Type', 'application/json')->withStatus(422);
    }
    
    // сохранение ...
    return $response->withStatus(201);
});

Запрос с пустым именем вернёт:

{"errors":{"name":"Имя должно быть строкой от 1 до 100 символов"}}

Тестирование API v1

Как написать автоматические тесты для маршрутов?

С Slim используйте PHPUnit и встроенный Slim\Psr7\Factory\ServerRequestFactory:

<?php
use PHPUnit\Framework\TestCase;
use Slim\Psr7\Factory\ServerRequestFactory;
use Slim\Factory\AppFactory;

class UserApiTest extends TestCase
{
    public function testGetUsersReturnsJson()
    {
        $app = AppFactory::create();
        // настройка маршрутов как в основном приложении
        $app->get('/v1/users', function ($request, $response) {
            $response->getBody()->write(json_encode(['data' => []]));
            return $response->withHeader('Content-Type', 'application/json');
        });
        
        $request = (new ServerRequestFactory)->createServerRequest('GET', '/v1/users');
        $response = $app->handle($request);
        
        $this->assertEquals(200, $response->getStatusCode());
        $this->assertStringContainsString('application/json', $response->getHeaderLine('Content-Type'));
    }
}

Результат выполнения теста будет зелёным, если API отвечает корректно.