Качественная разработка API невозможна без документации. В этом уроке мы разберем, как описывать endpoints (конечные точки) вашего REST API. Это критически важно для того, чтобы фронтенд-разработчики и внешние клиенты понимали, как использовать ваш код.
Документирование включает описание:
- Метода запроса (GET, POST, PUT, DELETE).
- URL адреса и параметров пути.
- Тела запроса (формат данных, обязательные поля).
- Кодов ответа (200 OK, 404 Not Found, 400 Bad Request) и структуры ответа.
Мы рассмотрим примеры оформления документации (например, в стиле OpenAPI/Swagger) и потренируемся читать и составлять такие описания. Эти задания и тесты помогут вам структурировать знания о взаимодействии клиент-сервер.
- Модуль 1: Основы синтаксиса PHP
- Модуль 2: Переменные и типы данных
- Модуль 3: Операторы
- Модуль 4: Условные конструкции
- Модуль 5: Циклы
- Модуль 6: Массивы
- Индексированные массивы.
- Ассоциативные массивы.
- Многомерные массивы.
- Добавление элементов в массив.
- Удаление элементов из массива.
- Функция count().
- Функция array_push() и array_pop().
- Функция array_shift() и array_unshift().
- Функция array_merge().
- Функция array_slice().
- Функция array_splice().
- Функция in_array().
- Функция array_search().
- Функция array_keys() и array_values().
- Функция array_unique().
- Функция array_reverse().
- Сортировка: sort(), rsort().
- Сортировка: asort(), arsort().
- Сортировка: ksort(), krsort().
- Функция array_map().
- Функция array_filter().
- Функция array_reduce().
- Функция array_walk().
- Функция array_column().
- Деструктуризация массивов.
- Iterator интерфейс
- Модуль 7: Функции
- Объявление функций.
- Вызов функций.
- Параметры функций.
- Возврат значений return.
- Значения параметров по умолчанию.
- Передача по значению.
- Передача по ссылке.
- Переменное количество аргументов.
- Оператор распаковки ....
- Типизация параметров.
- Типизация возвращаемых значений.
- Nullable типы.
- Union типы (PHP 8).
- Именованные аргументы (PHP 8).
- Анонимные функции.
- Стрелочные функции.
- Замыкания и use.
- Рекурсивные функции.
- Глобальные переменные в функциях.
- Статические переменные в функциях.
- IteratorAggregate интерфейс
- Модуль 8: Работа со строками
- Одинарные и двойные кавычки.
- Экранирование символов.
- Heredoc и Nowdoc синтаксис.
- Функция strlen().
- Функция substr().
- Функция str_replace().
- Функция strpos() и strrpos().
- Функция explode() и implode().
- Функция trim(), ltrim(), rtrim().
- Функция strtolower() и strtoupper().
- Функция ucfirst() и ucwords().
- Функция str_repeat().
- Функция htmlspecialchars().
- Модуль 9: Суперглобальные переменные
- Модуль 10: Работа с формами
- Модуль 11: Работа с файлами
- Модуль 12: Дата и время
- Модуль 13: Регулярные выражения
- Модуль 14: Сессии и Cookie
- Модуль 15: Include и Require
- Модуль 16: Объектно-ориентированное программирование
- Модуль 17: Пространства имен
- Модуль 18: Обработка ошибок и исключений
- Модуль 19: Работа с JSON и XML
- Модуль 21: PDO - PHP Data Objects
- Модуль 22: Composer и зависимости
- Модуль 23: cURL и HTTP запросы
- Модуль 24: REST API
- HTTP методы в REST.
- CORS заголовки.
- Документирование endpoints.
- Модуль 25: Безопасность
- Модуль 28: Работа с изображениями
- Модуль 29: Отправка email
- Модуль 30: Паттерны проектирования
- Модуль 31: Тестирование
- Модуль 32: Продвинутые возможности PHP 8+
1. Методы и действия
В левой колонке перечислены основные HTTP-методы, которые используются при создании REST API. В правой колонке — описания типичных действий, которые выполняет каждый из этих методов над ресурсом. Сопоставьте каждый HTTP-метод с соответствующим ему описанием действия. Обратите внимание, что в REST-архитектуре каждый метод имеет строго определённое семантическое значение, и правильное сопоставление важно для корректного документирования endpoints API.
GETPOSTPUTPATCHDELETE2. Компоненты запроса и ответа
В документации REST API каждый endpoint описывается с указанием того, какие данные клиент отправляет серверу (Request) и что сервер возвращает клиенту (Response). Перед вами список элементов, которые обычно встречаются в описании HTTP-запросов и ответов. Разнесите их по двум категориям: «Request (Запрос)» — то, что клиент передаёт серверу, и «Response (Ответ)» — то, что сервер отправляет обратно клиенту. Каждый элемент должен попасть ровно в одну категорию.
3. Анализ описания эндпоинта
В приведённом ниже фрагменте документации к REST API выделите три типа элементов: URL эндпоинта (обычно начинается с /api/ или /v1/, содержит параметры в фигурных скобках), HTTP-метод (GET, POST, PUT, DELETE и т.д.) и описание успешного ответа (обычно начинается с «Возвращает», «Успешный ответ» или содержит статус-код 200/201). Для каждого выделенного сегмента выберите соответствующий тип из списка ниже.
{{GET /api/v1/users/{id}~|~t1}}
Получить информацию о пользователе по его идентификатору.
{{Возвращает объект пользователя в формате JSON с кодом 200 OK.~|~t2}}
Параметры пути:
• id — идентификатор пользователя (обязательный)
4. Обязательные параметры
Перед вами таблица описания параметров эндпоинта REST API, представленная в популярном формате документации (OpenAPI/Swagger). В колонке «Required» указано, является ли параметр обязательным для передачи в запросе. Ваша задача — внимательно изучить таблицу и выделить кликом только те параметры, у которых в колонке «Required» стоит значение «Yes» (или true). Параметры с пустой ячейкой, значением «No», «false» или любым другим — отмечать не нужно. Обратите внимание, что обязательность может быть указана как текстом «Yes», так и булевым значением true.
| Parameter | Type | Description | Required |
|---|---|---|---|
| {{user_id~|~t1}} | integer | Идентификатор пользователя | {{Yes~|~t2}} |
| {{email~|~t3}} | string | Email адрес (для уведомлений) | {{No~|~t4}} |
| {{role~|~t5}} | string | Роль пользователя в системе | {{true~|~t6}} |
| {{timezone~|~t7}} | string | Часовой пояс (по умолчанию UTC) | |
| {{notify~|~t8}} | boolean | Отправлять уведомления на email | {{false~|~t9}} |
| {{api_key~|~t10}} | string | Ключ доступа к API | {{Yes~|~t11}} |
5. Ожидаемый статус
В документации вашего REST API указано, что успешное создание нового пользователя через POST-запрос на endpoint /api/users должно возвращать HTTP-статус 201 Created. Клиент сформировал полностью корректный запрос: отправил JSON с обязательными полями (name, email, password), все данные прошли валидацию на сервере, пользователь успешно сохранён в базе данных. Проанализируйте ситуацию и выберите код HTTP-статуса, который сервер вернёт в ответ на этот запрос в соответствии со стандартами документирования REST API.
POST /api/users
Создаёт нового пользователя.
Успешный ответ:
• Статус:
201 Created• Location:
https://api.example.com/users/{id}• Тело ответа: данные созданного пользователя
6. Заполнение шаблона документации
В этом задании вы отрабатываете правильное документирование REST API endpoints в соответствии со стандартами. Заполните пропуски в шаблоне описания маршрута так, чтобы полностью соответствовать операции получения информации о конкретном пользователе по его идентификатору. Укажите корректный HTTP-метод и код успешного ответа, который возвращается при успешном выполнении запроса. Обратите внимание, что путь содержит параметр в фигурных скобках — это стандартный способ обозначения динамического сегмента в маршрутах REST API.
Path: /users/{id}
Response: input2S OK
7. Описание ошибки
В документации REST API нужно правильно описать ошибку с кодом 404 Not Found. Соберите полное описание ответа, используя выпадающие списки и выбирая подходящие фразы из банка токенов. В реальной документации (OpenAPI/Swagger, Postman, README API) описание ошибки 404 обычно содержит указание, что запрошенный ресурс не найден на сервере. Выберите корректные части фразы из предложенных вариантов, чтобы получить стандартное и понятное сообщение об ошибке.
При попытке получить несуществующий ресурс сервер возвращает статус 404 Not Found и тело ответа:
{
"input1S": "input2S",
"message": "The requested input3S was input4S on this server."
}
8. Структура OpenAPI (YAML)
Перед вами строки YAML-описания OpenAPI 3.0 (фрагмент спецификации). Они перемешаны и имеют неправильную вложенность. Ваша задача — расставить их в строго правильном порядке, чтобы получилась корректная иерархия ключей: paths → /users → get → responses → 200. Обратите внимание на отступы: каждый уровень вложенности в YAML обозначается двумя пробелами. Правильная структура должна соответствовать официальному формату OpenAPI Specification (OAS 3.0.x).
paths: responses: summary: Получить список всех пользователей schema: /users: get: application/json: content: 200: description: Список пользователей9. Неверный глагол
В этом фрагменте документации REST API описан эндпоинт для получения списка товаров, однако указан неправильный HTTP-метод. Метод, используемый для чтения данных (получения ресурса), должен быть GET, а не POST. Найдите строку, где указан неверный глагол, и замените его на правильный. Ошибка очевидна и касается только одного сегмента текста.
Параметры запроса: page, limit (опционально)
Ответ: 200 OK, JSON-массив объектов товара
10. PHPDoc для API контроллера
В REST API контроллерах для корректного документирования эндпоинтов часто используют PHPDoc-блок с аннотациями. Из предложенных строк соберите правильный PHPDoc-блок для метода контроллера, который обрабатывает POST-запрос по маршруту и добавляет новый элемент. В блоке должны присутствовать только три аннотации: @Route (с указанием пути и метода), @Method('POST') и @Description с кратким описанием действия. Некоторые строки являются лишними — их включать в решение не нужно. Обратите внимание на правильный порядок и синтаксис аннотаций в PHPDoc.
/** * @Route("/api/items", methods={"POST"}) * @Method("POST") * @Description("Adds a new item") */ * @param Request $request * @return JsonResponse * @ApiResource * @Route("/items/create")11. Чтение пути
В документации REST API динамические части пути (path parameters) обозначаются фигурными скобками { }. Например, в маршруте /api/v1/users/{id} параметр id является переменным — при запросе вместо него подставляется конкретное значение. Внимательно посмотрите на приведённый ниже путь эндпоинта и определите имя динамического параметра. Введите только имя параметра без фигурных скобок и без лишних символов.
Какой параметр в этом пути является динамическим?
