Памятка по дизайну API

Создавайте API с мыслью о потребителях — как самостоятельный продукт.

• Не для конкретного пользовательского интерфейса.
• Обеспечьте гибкость/настраиваемость каждой конечной точки (см. № 5, 6 и 7).
• Ешьте свой собственный опыт, даже если вам нужно смоделировать пример пользовательского интерфейса.

Используйте метафору коллекции.

• Два URL-адреса (конечные точки) на ресурс:
  • Коллекция ресурсов (например, /orders)
  • Отдельный ресурс в коллекции (например, /orders/{orderId}).
• Используйте формы множественного числа («заказы» вместо «заказ»).
• Альтернативные имена ресурсов с идентификаторами в качестве узлов URL (например, /orders/{orderId}/items/{itemId})
• Держите URL-адреса как можно короче. Желательно не более трех узлов на URL.

Используйте существительные в качестве имен ресурсов (например, не используйте глаголы в URL-адресах).

Сделайте представления ресурсов значимыми.

• «Никаких голых удостоверений личности!» Нет простых идентификаторов, встроенных в ответы. Используйте ссылки и ссылочные объекты.
• Дизайн представлений ресурсов. Не просто представляйте таблицы базы данных.
• Объединить представления. Не выставляйте таблицы отношений как два идентификатора.

Поддержка фильтрации, сортировки и разбивки на страницы в коллекциях.

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

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

Используйте имена методов HTTP, чтобы что-то означать:

• POST — создание и другие неидемпотентные операции.
• PUT — обновить.
• GET — прочитать ресурс или коллекцию.
• DELETE — удалить ресурс или коллекцию.

Используйте коды состояния HTTP, чтобы они были значимыми.

• 200 — Успех.
• 201 — Создан. Возврат при успешном создании нового ресурса. Включите заголовок «Местоположение» со ссылкой на вновь созданный ресурс.
• ошибка 400, неверный запрос. Проблемы с данными, такие как недопустимый JSON и т. д.
• 404 — Не найдено. Ресурс не найден в GET.
• 409 — Конфликт. Возникнут повторяющиеся данные или недопустимое состояние данных.

Используйте форматы точек времени ISO 8601 для дат в представлениях.

Учитывайте связанность, используя стратегию связывания. Некоторые популярные примеры:

• ХАЛ
• Сирена
• JSON-LD
• Коллекция+JSON

Используйте OAuth2 для защиты вашего API.

• Используйте токен носителя для аутентификации.
• Требовать HTTPS/TLS/SSL для доступа к вашим API. Этого требуют токены носителя OAuth2. Не зашифрованная связь через HTTP позволяет легко подслушивать и выдавать себя за другое лицо.

Используйте согласование Content-Type для описания полезной нагрузки входящего запроса.

Например, предположим, что вы ставите рейтинги, в том числе "палец вверх"/"палец вниз" и пятизвездочный рейтинг. У вас есть один способ создать рейтинг: POST /ratings

Как вы различаете входящие данные в сервис, чтобы он мог определить, какой это тип рейтинга: большой палец вверх или пять звезд?

Есть соблазн создать по одному маршруту для каждого типа рейтинга: POST /ratings/five_star и POST /ratings/thumbs_up.

Однако, используя согласование Content-Type, мы можем использовать один и тот же маршрут POST/ratings для обоих типов. Установив заголовок Content-Type в запросе на что-то вроде Content-Type: application/vnd.company.rating.thumbsup или Content-Type: application/vnd.company.rating.fivestar , сервер может определить, как обрабатывать входящий рейтинг. данные.

Эволюция над версиями. Однако при управлении версиями используйте заголовок Accept вместо указания версии в URL-адресе.

• Управление версиями через URL-адрес означает версию «платформы», и вся платформа должна иметь версию одновременно, чтобы включить стратегию связывания.
• Версионирование через заголовок Accept — это версионирование ресурса.
• Дополнения к ответу JSON не требуют управления версиями. Однако дополнения к телу запроса JSON, которые «обязательны», вызывают проблемы и могут потребовать управления версиями.
• Гипермедиа-связывание и управление версиями в любом случае проблематичны — сведите их к минимуму.
• Обратите внимание, что версия в URL-адресе, хотя и не рекомендуется, может использоваться как «платформенная» версия. Он должен отображаться как первый узел в пути и не иметь разных версий отдельных конечных точек (например, api.example.com/v1/...).

Рассмотрите возможность кэширования. Как минимум используйте следующие заголовки ответов:

• ETag — произвольная строка для версии представления. Не забудьте включить тип носителя в хеш-значение, потому что это создает другое представление. (например: ETag: "686897696a7c876b7e")
• Date — дата и время возврата ответа (в формате RFC1123). (пример: Дата: воскресенье, 06 ноября 1994 г., 08:49:37 по Гринвичу)
• Cache-Control — максимальное количество секунд (максимальный возраст), в течение которого ответ может быть кэширован. Однако, если кэширование ответа не поддерживается, значением является no-cache. (например: Cache-Control: 360 или Cache-Control: no-cache)
• Expires — если указан максимальный возраст, содержит отметку времени (в формате RFC1123) для истечения срока действия ответа, которая представляет собой значение даты (например, now) плюс максимальный возраст. Если кэширование ответа не поддерживается, этот заголовок отсутствует. (пример: Истекает: воскресенье, 06 ноября 1994 г., 08:49:37 по Гринвичу)
• Pragma — Когда Cache-Control имеет значение «без кеша», для этого заголовка также устанавливается значение «без кеша». В противном случае его нет. (например: Прагма: без кеша)
• Last-Modified — отметка времени последней модификации самого ресурса (в формате RFC1123). (пример: Last-Modified: Sun, 06 ноября 1994 г., 08:49:37 по Гринвичу)

Убедитесь, что ваши операции GET, PUT и DELETE являются идемпотентными . Не должно быть побочных эффектов от операций.