Понимание вопросов проектирования API Rest для инженеров-программистов

• — сбор пользователей
• — один пользователь
• — заказы, принадлежащие конкретному пользователю
• — единый заказ

Глубина должна быть ограниченной. Вложение более двух или трех уровней затрудняет чтение и поддержание URI. Для сложных отношений рассмотрите возможность использования параметров запроса или выделенных ресурсов. Избегайте глаголов, таких как , потому что метод HTTP уже передает действие. Последовательность жизненно важна: если вы используете для сбора, не используйте для другой коллекции.

Как справиться с ошибками?

Ответы на ошибки должны быть информативными и последовательными. Используйте правильный код состояния HTTP:

• 400 Bad Request — некорректный запрос (например, недостающее требуемое поле, недействительный JSON).
• 401 Несанкционированные — Пропущенные или недействительные учетные данные для аутентификации.
• 403 Запрещено — Подлинный пользователь не имеет разрешения.
• 404 Не найдено — Ресурса не существует.
• 409 Conflict — Запрос конфликтует с текущим состоянием (например, дубликатная запись).
• 422 Необработанная сущность — ошибки проверки в органе запроса.
• 500 Внутренняя ошибка сервера — Неожиданный сбой сервера.

В дополнение к коду состояния орган реагирования должен иметь последовательную структуру.

{
 "error": {
 "code": "USER_NOT_FOUND",
 "message": "User with ID 42 not found.",
 "details": "..."
 }
}

Предоставьте машиночитаемый код ошибки, считываемое человеком сообщение и, возможно, поле деталей с ошибками проверки или идентификатор трассировки для отладки. Не выставляйте следы стека в производственных ответах.

А как же версия?

Версия обеспечивает обратную совместимость, чтобы существующие клиенты не были сломаны, когда вы добавляете новые функции или меняете поведение. Существуют три общих подхода:

• URI-версия — Включите версию в путь (например, ). Это самый популярный подход, потому что он явный и простой в маршрутизации.
• Редактирование заголовка — Используйте заголовок пользовательского запроса (например, ). Это сохраняет URI чистым, но требует от клиентов правильно установить заголовок.
• Версия параметров запроса — Добавьте параметр . Обычно это не рекомендуется, потому что он загромождает строки запросов и может мешать кэшированию.

Версия URI является наиболее простой для большинства команд.Сохранить версии в течение разумного периода (не менее двух лет) и обесценить их с четкой связью.

Как реализовать пагинацию, фильтрацию и сортировку?

Конечные точки сбора (например, ) могут возвращать тысячи записей. Без пагинации производительность ухудшается и воздушные шары над сетью.

• Пагинация — Используйте кодирование на основе курсора или офсетное/лимитное.) Легко реализовать, но может стать неэффективным на больших наборах данных. На основе курсора (]) более надежная и последовательная. Включите метаданные кодирования в ответ, такие как , и .
• Фильтрация — Используйте параметры запроса для логического фильтрования ресурсов. Последовательно применяйте одни и те же шаблоны фильтров в конечных точках.
• Сортировка — Разрешить сортировку с такими параметрами, как или для убывающего порядка.Документируйте доступные поля сортировки.

Поддержка этих операций с самого начала не позволяет вам рефакторировать конечные точки позже, когда потребители неизбежно запрашивают их.

Как управлять аутентификацией и авторизацией?

API REST не имеют состояния, поэтому аутентификация должна происходить с каждым запросом. Наиболее распространенный подход заключается в использовании маркеров-носителей , передаваемых в заголовке . OAuth 2.0 является отраслевым стандартом безопасности API. Для внутренних API ключи API (проходимые в пользовательском заголовке) иногда достаточны, но они предлагают более слабую безопасность, потому что утечка ключа не может быть легко отменена без изменения самого ключа.

Авторизация (что может сделать пользователь) обычно осуществляется на стороне сервера путем проверки ролей или разрешений, связанных с аутентифицированной личностью. Избегайте встраивания логики авторизации в клиент; всегда проверяйте на сервере.

Императивность

Идемпотентность гарантирует, что выполнение одного и того же запроса несколько раз дает тот же результат, что и выполнение его один раз, без побочных эффектов. GET , PUT , DELETE и HEAD POST POST не является идемпотентным. Пост каждый раз — это создает новый ресурс. Для сценариев, где идемпотентность имеет решающее значение (например, обработка платежей), реализуйте ключи идемпотентности: клиенты отправляют уникальный ключ в заголовке (например, ), и сервер хранит первоначальный ответ, возвращая его для дублирующих запросов.

Как управлять кэшированием?

Кэширование повышает производительность и снижает нагрузку на сервер. HTTP-кэширование регулируется заголовками, такими как , , и . Для общедоступных API устанавливают соответствующие сроки службы кэша на стабильных ресурсах. Для динамических данных используют условные запросы: клиент отправляет с ETag, а сервер отвечает с , если ресурс не изменился. Это снижает потребление полосы пропускания.

Ненависть или ненависть?

HATEOAS (Hypermedia as the Engine of Application State) часто упоминается как ключевой дифференциатор REST, но на практике он редко полностью принимается. Идея заключается в том, что представление ресурса включает в себя ссылки на связанные действия, позволяя клиентам перемещаться по API без предварительного знания. Например, пользовательский ресурс может включать . Хотя добавление объектов ссылок к вашим ответам не является обязательным, добавление объектов ссылок может сделать API более доступными и уменьшить связь между клиентом и сервером. Начните с простых связей и расширяйте по мере необходимости.

Лучшие практики для REST API Design

Помимо ответа на отдельные вопросы, применение последовательного набора лучших практик поднимает ваш API от просто функционального до отличного.

Последовательность превыше всего

Используйте единые соглашения имен, структуры ответов и поведение во всех конечных точках. Если одна конечная точка возвращает 404 для отсутствующего ресурса, все должны. Если вы используете змеиный случай для ключей JSON, каждая конечная точка должна. Непоследовательность расстраивает разработчиков и увеличивает время интеграции.

Предоставить полную документацию

Хорошая документация является неотъемлемой частью API. Такие инструменты, как Swagger/OpenAPI, Directus (который включает в себя автоматическое создание документации API), и коллекции Postman помогают разработчикам быстро понять ваши конечные точки. Примеры запросов/ответов документов, коды ошибок, ограничения скорости и потоки аутентификации. Сохраняйте документацию синхронизированной с фактическим API.

Используйте стандартные коды состояния HTTP

Никогда не используйте 200 для ошибок или 500 для ошибок клиентов. Правильные коды состояния позволяют клиентам легко обнаруживать успех или сбой программно. Ссылка на код состояния HTTP .