Web-разработка

Советы по созданию хорошего дизайна API

14.02.2023

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

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

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

Когда вы заходите в веб-приложение, отправляете сообщение и переходите по 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: