Как правило, при обновлении и разработке с нуля API какого-либо сервиса ведутся долгие обсуждения именования, функциональности и структуры этого API. И это несмотря на то, что с годами были разработаны определенные правила, которые помогают найти общий язык при разработке.

Сначала разберемся с основами.

API  —  это аббревиатура термина Application programming interface (программный интерфейс приложения). Он представляет собой программное обеспечение, которое позволяет двум приложениям взаимодействовать друг с другом. В этой статье мы сосредоточимся на веб-API.

Структура web-приложения

Когда вы заходите в веб-приложение, отправляете сообщение и переходите по URL-адресу, вы используете API какого-то приложения.

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

  • GET  —  запрашивает представление указанного ресурса. GET-запросы должны только извлекать данные.
  • POST  —  отправляет данные на указанный ресурс.
  • PUT  —  заменяет все текущее представление целевого ресурса данными запроса.
  • DELETE  —  удаляет указанный ресурс.
  • PATCH  —  применяет частичные изменения к ресурсу.

Об остальных методах более подробно можно прочитать здесь.

На протяжении многих лет возникали различные типы архитектур и протоколов API. Они отличаются тем, как определяют типы данных и команды, а также по своим возможностям. Одно время наиболее популярным был протокол на основе XML, но сейчас его практически заменил JSON.

Наиболее распространенная архитектура API в современном мире  — это REST (representational state transfer, передача репрезентативного состояния). При использовании REST обязательно следовать правилам JSON и формировать запросы в допустимом JSON-формате. Кроме того, хороший API должен соответствовать следующим правилам.

  • API должен быть отделен от серверной части, хранилища данных, клиента и т.д. Это должен быть отдельный уровень  —  из соображений безопасности и гибкости.
  • Отсутствие состояния  —  разные запросы не должны ничего знать друг о друге и обрабатываться независимо. Это также означает, что каждый запрос должен включать всю информацию, необходимую для его обработки.
  • API должен работать одинаково независимо от клиента, отправляющего запрос (например, веб-сервера и балансировщика нагрузки).
  • REST API обычно отправляют статические ресурсы, но в некоторых случаях ответы могут содержать и исполняемый код (например, апплеты Java). В этих случаях код должен выполняться только по требованию.
  • Возможность кэширования  —  ресурсы должны быть доступны для кэширования на стороне клиента или сервера. Цель в том, чтобы повысить производительность на стороне клиента при одновременном повышении масштабируемости на стороне сервера. Тем не менее существуют специальные заголовки для управления поведением кэша, такие как Cache-Control.
  • Обрабатывайте ошибки и возвращайте соответствующие коды ошибок. У каждой ошибки есть конкретные коды. Вместо того чтобы выдавать пользователю внутреннюю ошибку, обработайте ее и отправьте соответствующий код с сообщением (например, 404  —  не найдено). Список кодов можно найти по ссылке.
  • Не забывайте, что API должен быть идемпотентным. Это означает, что его можно вызывать много раз с одним и тем же результатом. Пользователи иногда могут дублировать запросы к API. Эти повторяющиеся запросы могут быть непреднамеренными (или преднамеренными из-за тайм-аута или проблем с сетью). Таким образом, API должен быть отказоустойчивым, чтобы повторяющиеся запросы приводили к одинаковым результатам. Только POST-запрос не является идемпотентным.
  • Для фиксации документации по API задействуйте Swagger или другой подобный инструмент. Документация  —  важная часть процесса (если кто-то когда-нибудь собирается пользоваться этим API на практике).

Существуют также принципы хорошего тона в именовании эндпойнтов. Вот несколько из них.

  • Используйте только существительные: эндпойнт должен быть назван существительными, которые определяют содержимое ресурса, вместо добавления глагола для выполняемой функции. Например, назовите конечную точку /users и используйте различные методы HTTP для работы с сущностью users вместо создания нескольких эндпойнтов, таких как /get-user, /add-user и т.д.
  • Используйте понятные имена: название эндпойнта должно быть ясным и интуитивно понятным. Не используйте сокращения и аббревиатуры, если только это не очевидно  —  /ids понятнее и предпочтительнее, чем /identification-numbers.
  • Постройте иерархию с помощью косых черт: сгруппируйте эндпойнты в логические группы. /departments/ids и /departments/managers лучше, чем /departments-ids и /departments-managers.
  • Используйте только строчные буквы: URI чувствительны к регистру (согласно спецификации), поэтому лучше избегать верхнего регистра, если в нем нет необходимости.
  • Используйте “-” для разделения слов: разные слова в названии эндпойнта обычно разделяются символом “-”, а не подчеркиванием и с помощью “верблюжьего регистра”.
  • Избегайте специальных символов: URL-адреса можно отправлять и получать только с набором символов ASCII, поэтому допустимы только символы из этого набора. Также есть некоторые ожидаемые, но небезопасные символы, такие как “%”, ”[]”, ”{}”, ”|” и ”<>”. Но лучше избегать и их по мере возможности.

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

Теперь с учетом изложенных правил взглянем на примеры реальных API:

Читайте также:

Читайте нас в Telegram, VK и Дзен

Перевод статьи Roman Kyslyi: Good API design, bad API design

Предыдущая статья7 способов сократить код JavaScript
Следующая статья8 полезных команд NPM для фронтенд-инженера