Выбор Request-Response парадигмы API: REST, RPC или GraphQL?
Выбор подходящего формата API позволит в будущем вносить изменения, экономя время, силы и деньги. В этой статье — обзор популярных форматов.
API определяет интерфейс, предоставляющий данные сервиса другим приложениям. Выбор правильного формата API крайне важен. Бизнес не всегда учитывает все факторы, выбирая формат. В результате не хватает возможности для добавления новых фич, которые могут понадобиться в дальнейшем.
Чтобы сэкономить время, силы, а самое главное деньги, стоит посмотреть на best practices, которые применяются на текущий момент. Это поможет разработать API, который позволит вносить необходимые изменения в будущем. За прошедшие годы появилось несколько форматов API, рассмотрим самые популярные из них.
Request-Response APIs
Первую группу API, которую мы рассмотрим, можно выделить как Request-Response API. Основные отличия данной группы:
- Интерфейс предоставляется через веб-сервер на основе HTTP протокола.
- API определяет набор эндпоинтов.
- Клиенты отправляют запросы для работы с данными(получить/удалить/изменить) на данные эндпоинты.
- Ответ в формате JSON или XML.
Самые популярные request-response API: REST, RPC и GraphQL.
REST
Самый популярный подход на данный момент. Используется такими поставщиками API, как, например, Google, Twitter и GitHub.
Когда мы говорим про REST, мы говорим про ресурсы. Ресурс — это объект, который может быть идентифицирован, назван, адресован или обработан в сети. REST представляет данные как ресурсы и использует стандартные HTTP-методы для представления транзакций создания, чтения, обновления и удаления этих ресурсов, то есть стандартные CRUD операции. По сути, все бизнес-сущности, которыми оперирует сервис, могут быть определены как ресурсы.
Общие правила, которым следует RESTful API:
- Ресурс является частью URL.
- Существительные вместо глаголов, вместо
/getUserInfo/123
используем/users/123
. - Для каждого ресурса создается два URL, один для коллекции, один для экземпляра коллекции,
/users
иusers/123
. - HTTP-методы GET, POST, UPDATE и DELETE информируют сервер о том, какое действие нужно совершить над данным ресурсом. Различные методы, примененные к одному и тому же ресурсу, выполняют различную функциональность.
- Стандартные коды состояния ответа HTTP возвращаются сервером, указывая на успех или неудачу. Как правило, коды в диапазоне 2XX указывают на успех, коды 3XX указывают на перемещение ресурса, а коды в диапазоне 4XX указывают на ошибку на стороне клиента (например, отсутствие обязательного параметра или слишком много запросов). Коды в диапазоне 5XX указывают на ошибки на стороне сервера.
- Ресурс, который существует только в другом ресурсе, должен быть представлен как подресурс, а не как ресурс верхнего уровня в URL-адресе. Например issues не могут существовать отдельно от репозитория, поэтому URL создания нового issue в GitHub API выглядит таким образом — /repos/:owner/:repo/issues
Помимо типичных операций CRUD, API-интерфейсы REST могут иногда нуждаться в представлении операций, не относящихся к CRUD. В этом случае обычно используются следующие подходы:
- Передавать действие в теле метода. Например, GitHub использует данный подход для архивации репозитория (прим. PATCH /repos/:owner/:repo).
- Трактовать действие как подресурс. API GitHub использует этот шаблон для блокировки и разблокировки issue (прим. PUT /repos/:owner/:repo/issues/:number/lock).
- Использовать отдельный ресурс. Некоторые операции, такие как поиск, ещё сложнее вписать в парадигму REST. Типичная практика в этом случае — использовать только команду действия в URL-адресе API (прим. GET /search/code?q=:query).
Плюсы:
- Стандартное имя метода, формат аргументов и коды состояния.
- Использует функционал HTTP.
- Легко поддерживать.
Минусы:
- Большой payload.
- Множественные HTTP-запросы.
Когда использовать:
Для API, предоставляющего CRUD-операции.
Remote Procedure Call (RPC)
Удаленный вызов процедур (RPC) — это одна из простейших парадигм API, в которой клиент вызывает исполнение блока кода на сервере. В то время как REST рассматривает всё как ресурсы, RPC рассматривает действия. Клиенты обычно передают имя метода и аргументы серверу и получают обратно JSON или XML.
Правила RPC:
- Эндпоинты содержат имя выполняемой операции.
- Вызовы API выполняются с помощью наиболее подходящего HTTP-глагола: GET для запросов только для чтения и POST для других.
Пример:
Плюсы:
- Очень прост.
- Легковесный payload.
- Высокая производительность.
Минусы:
- Труден в обнаружении.
- Практически нет стандартизации.
- Может быть создано слишком много эндпоинтов.
Когда использовать:
Для API, предоставляющего действия, которые сложно инкапсулировать в CRUD операциях.
GraphQL
GraphQL — это язык запросов для API, который в последнее время приобрел значительную популярность. Он был разработан внутри Facebook в 2012 году до публичного выпуска в 2015 году. GraphQL позволяет клиентам определять структуру требуемых данных. Сервер возвращает именно эту структуру
Пример запроса:
Пример ответа:
В отличие от REST и RPC API, GraphQL требует только один эндпоинт URL. Также вам не нужны разные HTTP-методы для описания операции. Вместо этого вы указываете в теле JSON выполняете ли вы запрос или мутацию. GraphQL поддерживает методы GET и POST.
Плюсы:
- Один запрос.
- Возможность добавлять новые поля и типы в GraphQL API, не затрагивая существующие запросы.
- Проще отказаться от использования существующих полей.
- Выполняя анализ логов, поставщик API может выяснить, какие клиенты используют определённое поле. Вы можете скрыть устаревшие поля и удалить их, когда их не используют клиенты. С REST и RPC API сложнее определить, какие клиенты используют устаревшее поле, что затрудняет удаление.
- Small payload.
- GraphQL строго типизирован. Во время разработки проверка типов GraphQL помогает гарантировать, что запрос синтаксически верен и действителен.
- GraphiQL — встроенная в браузер IDE для изучения GraphQL. Данный инструмент позволяет пользователям писать, проверять и тестировать запросы GraphQL в браузере.
Минусы:
- Серверу требуется дополнительная обработка для анализа сложных запросов и проверки параметров.
- Оптимизация производительности запросов GraphQL тоже может быть сложной задачей.
- Внутри компании легко предсказать варианты использования и отладить узкие места в производительности, но при работе с внешними разработчиками эти варианты использования становятся трудными для понимания и оптимизации.
Когда использовать: