Большинство из нас, разработчиков веб-приложений, в повседневной жизни создают REST API. API - основные средства связи между системами. В этой статье я расскажу, как лучше разрабатывать API, чтобы не совершать типичные ошибки.
Требования Джеффа Безоса: ключ к успеху
Многие из вас уже наверняка знают о требованиях Джеффа Безоса к разработчикам в Amazon. Если вы не слышали об этом, ниже перечислены основные его положения:
- Отныне все группы разработчиков должны раскрывать свои данные и функциональные средства через сервисные интерфейсы;
- Группы разработчиков должны связываться друг с другом с помощью этих интерфейсов;
- Больше никаких форм межпроцессного взаимодействия не допускается: никаких прямых ссылок и считываний данных других групп, никакой модели общей памяти, никаких «лазеек». Единственная разрешенная форма связи осуществляется через служебные интерфейсы по сети;
- Неважно, какую технологию используют разработчики: HTTP, Cobra, Pubsub, встроенные протоколы;
- Больше никаких форм межпроцессного взаимодействия не допускается: никаких прямых ссылок и считываний данных других групп, никакой модели общей памяти, никаких «лазеек». Единственная разрешенная форма связи осуществляется через служебные интерфейсы по сети;
- Больше никаких форм межпроцессного взаимодействия не допускается: никаких прямых ссылок и считываний данных других групп, никакой модели общей памяти, никаких «лазеек». Единственная разрешенная форма связи осуществляется через служебные интерфейсы по сети;
- Все без исключения сервисные интерфейсы с самого начала должны проектироваться выгружаемыми. Это значит, что группа должна планировать интерфейс так, чтобы его можно было раскрыть остальным разработчикам. Исключения не допускаются;
- Все, кто не слушаются этих правил, будут уволены.
В итоге эти требования оказались ключом к успеху Amazon. Компания смогла создавать эластичные системы, а позднее могла предложить эти услуги в лице Amazon Web Services.
Принципы разработки RESTful API
Для разработки RESTful API нужно следовать следующим принципам:
Простота
Нужно убедиться в простоте базового URL для API. Например, если нужно разработать запрос для продуктов, должно получаться так:
/products
/products/12345
Первый запрос к API - для всех продуктов, второй - для специфического продукта.
Используйте существительные, а не глаголы
Многие разработчики совершают эту ошибку. Обычно они забывают, что у нас есть HTTP методы для лучшего описания API, и в итоге используют глаголы в URL. Например, запрос для получения всех продуктов звучит так:
/products
...а не так:
/getAllProducts
Так часто поступают при создании URL.
Правильные HTTP методы
В RESTful API существуют различные методы, которые описывают тип операции, которую будет осуществлять API.
- GET - для получения ресурса или группы ресурсов;
- POST - для создания ресурса или группы ресурсов;
- PUT/PATCH - для обновления уже существующего ресурса или группы ресурсов;
- DELETE - для удаления уже существующего ресурса или группы ресурсов.
Нужно обязательно убедиться в том, что вы используете верный HTTP метод для каждой операции.
Не забывайте о множественном числе
Эта тема еще стоит под вопросом. Некоторым нравится называть URL ресурсов во множественном числе, некоторым - в единственном. Пример:
/products
/product
Мне нравится использовать множественное число, потому что в таком случае не создается путаница: работаем ли мы с одним ресурсом или с группой ресурсов? Также не нужно дополнять базовые URL, например, добавлением all: /product/all.
Кому-то может не нравиться мой подход. Мой единственный совет - делайте так, чтобы в проекте все было единообразно.
Параметры
Иногда нужен API, который должен работать не только по имени. В таком случае для разработки API понадобятся параметры запроса.
нужно использовать /products?name='ABC', а не /getProductsByName;
нужно использовать /products?type='xyz', а не /getProductsByType.
В таком случае URL не будут слишком длинными, а структура останется простой.
Правильные HTTP коды
Существует множество HTTP кодов. Многие из нас используют только два из них: 200 и 500! Это плохая методика. Ниже перечислены часто используемые HTTP коды:
- 200 OK - самый часто используемый код, свидетельствующий об успехе операции;
- 201 CREATED - используется, когда с помощью метода POST создается ресурс;
- 202 ACCEPTED - используется, чтобы сообщить, что ресурс принят на сервер;
- 400 BAD REQUEST - используется, когда со стороны клиента допущена ошибка в вводе;
- 401 UNAUTHORIZED / 403 FORBIDDEN - используются, если для выполнения операции требуется аутентификация пользователя или системы;
- 404 NOT FOUND - используется, если в системе отсутствуют искомые ресурсы;
- 500 INTERNAL SERVER ERROR - это никогда не используется просто так - в таком случае произошла ошибка в системе;
- 502 BAD GATEWAY - используется, если сервер получил некорректный ответ от предыдущего сервера.
Версии
Версии API - важная вещь. Различные компании используют версии по-разному: кто-то - как даты, кто-то - как параметры запросов. Мне нравится указывать версии до названия ресурса. Пример:
/v1/products
/v2/products
Мне также кажется, что стоит избегать использования /v1.2/products, так как это подразумевает, что API часто меняется. К тому же, точки в URL не так легко заметить. Так что чем проще, тем лучше.
Также хорошо бы сохранять совместимость с предыдущими версиями. В таком случае, если вы поменяете версию API, у пользователей будет время, прежде чем перейти на новую версию.
Разбиение на страницы
Обязательно нужно разбивать запрос на страницы, если вы работаете с API, который в качестве ответа может предоставить огромный объем данных. Если сбалансированность нагрузки не обеспечена, пользователь может обрушить сервер.
Всегда нужно иметь в виду, что структура API должна быть полностью защищена, в том числе от неосторожного обращения.
В таком случае стоит использовать limit и offset. Пример: /products?limit=25&offset=50. Также стоит установить эти настройки по умолчанию.
Поддерживаемые форматы
Также нужно выбирать то, как будет отвечать API. Большинство современных приложений используют JSON. Приложения старых версий должны пользоваться XML ответами.
Верные сообщения об ошибках
Всегда хорошо, чтобы у приложения был набор сообщений об ошибках, которые используются уместно. Например, в случае ошибки графические API на Facebook выдают такое сообщение:
{
"error": {
"message": "(#803) Some of the aliases you requested do not exist: products",
"type": "OAuthException",
"code": 803,
"fbtrace_id": "FOXX2AhLh80"
}
}
Я также видел некоторые примеры, в которых люди помещают в сообщения ссылку на ошибку, в которой рассказывается о ней и о способах избавления от проблемы.
Open API Specification
Чтобы все группы разработчиков в компании подчинялись одним и тем же принципам, будет полезно использовать Open API Specification. Open API позволяет проектировать API и делиться ей с потребителями в более простой форме.
Заключение
Довольно очевидно, что для лучшей связи отлично подойдут API. Если же они неудачно спроектированы, это вызовет только больше путаницы. Так что выкладывайтесь на полную в разработке, а дальше уже последует этап реализации.