БЛОГ · 5 ноября 2026

Контракт API на примере заметки: 200, 400 и 404

Рабочий PHP-пример: три ответа одного endpoint и одинаковая форма JSON-ошибок.

У одного адреса /note.php будут три исхода: заметка найдена, идентификатор неверный, записи с таким идентификатором нет. Если во всех случаях вернуть 200, клиенту придётся угадывать результат по тексту JSON. Зададим статусы и форму ошибки до подключения базы и интерфейса.

Один GET endpoint возвращает 200 с заметкой, 400 при неверном id и 404 для отсутствующей записи; форма JSON-ошибки одинакова.
Разные статусы помогают клиенту выбрать действие; форма ошибки остаётся стабильной.

Три запроса к одной заметке

Запрос Статус Смысл
GET /note.php?id=1 200 Заметка найдена
GET /note.php?id=0 400 Неверный идентификатор
GET /note.php?id=99 404 Идентификатор допустим, записи нет

Сохраните следующий код как note.php и запустите локально командой php -S localhost:8000. Записи здесь заданы массивом: это проверка контракта, не подключение к базе.

<?php
function respond(int $status, array $body): never {
    http_response_code($status);
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode($body, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
    exit;
}

if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'GET') {
    header('Allow: GET');
    respond(405, ['error' => ['code' => 'method_not_allowed', 'message' => 'Нужен GET']]);
}

$raw = $_GET['id'] ?? null;
$id = is_string($raw)
    ? filter_var($raw, FILTER_VALIDATE_INT, ['options' => ['min_range' => 1]])
    : false;
if ($id === false) {
    respond(400, ['error' => ['code' => 'invalid_id', 'message' => 'Неверный id']]);
}

$notes = [1 => ['id' => 1, 'title' => 'Первый HTML-документ']];
if (!isset($notes[$id])) {
    respond(404, ['error' => ['code' => 'note_not_found', 'message' => 'Заметка не найдена']]);
}
respond(200, $notes[$id]);

Сверьте статус с телом JSON

Откройте три адреса из таблицы во вкладке Network или выполните в PowerShell curl.exe -i "http://localhost:8000/note.php?id=1" (в Bash — curl -i "http://localhost:8000/note.php?id=1"), затем замените id на 0 и 99. Сравните HTTP-статус и тело JSON. Для ошибки объект всегда содержит error.code и error.message, но код различает недопустимый ввод и отсутствие записи.

Проверьте также ?id[]=1: PHP получит массив вместо строки, и этот обработчик вернёт 400 без предупреждения. Не включайте в ответ трассировки и настройки базы. Для закрытых заметок понадобится отдельное правило доступа; три показанных ответа его ещё не описывают. Как развивать такой контракт, показано в уроке об API, а проверка типов на границе — в уроке о типах и ошибках.

Категории: Обучение
← Все статьи