Аватарка пользователя Georgii Kliukovkin
Georgii Kliukovkin

Выбор Request-Response парадигмы API: REST, RPC или GraphQL?

Выбор подходящего формата API позволит в будущем вносить изменения, экономя время, силы и деньги. В этой статье — обзор популярных форматов.

24181

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. В этом случае обычно используются следующие подходы:

  1. Передавать действие в теле метода. Например, GitHub использует данный подход для архивации репозитория (прим. PATCH /repos/:owner/:repo).
  2. Трактовать действие как подресурс. API GitHub использует этот шаблон для блокировки и разблокировки issue (прим. PUT /repos/:owner/:repo/issues/:number/lock).
  3. Использовать отдельный ресурс. Некоторые операции, такие как поиск, ещё сложнее вписать в парадигму 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 для других.

Пример:

			POST /api/conversations.archive 
HOST slack.com 
Content-Type: application/x-www-form-urlencoded 
Authorization: token OAUTH-TOKEN 

channel=C01234
		

Плюсы:

  • Очень прост.
  • Легковесный payload.
  • Высокая производительность.

Минусы:

  • Труден в обнаружении.
  • Практически нет стандартизации.
  • Может быть создано слишком много эндпоинтов.

Когда использовать:

Для API, предоставляющего действия, которые сложно инкапсулировать в CRUD операциях.

GraphQL

GraphQL — это язык запросов для API, который в последнее время приобрел значительную популярность. Он был разработан внутри Facebook в 2012 году до публичного выпуска в 2015 году. GraphQL позволяет клиентам определять структуру требуемых данных. Сервер возвращает именно эту структуру

Пример запроса:

			POST /graphql 
HOST api.github.com 
Content-Type: application/json 
Authorization: bearer OAUTH-TOKEN 
{ 
   user(login: "kliukovkin") { 
    id 
    name 
    company 
    createdAt 
   } 
}
		

Пример ответа:

			{   "data": { 
      "user": { 
         "id": "MDQ6VXNlcjY1MDI5", 
         "name": "Georgii Kliukovkin", 
         "company": "myCompany", 
         "createdAt": "2009-03-19T21:00:06Z" 
      } 
   } 
}
		

В отличие от 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 тоже может быть сложной задачей.
  • Внутри компании легко предсказать варианты использования и отладить узкие места в производительности, но при работе с внешними разработчиками эти варианты использования становятся трудными для понимания и оптимизации.

Когда использовать:

На данный момент этот блок не поддерживается, но мы не забыли о нём!Наша команда уже занята его разработкой, он будет доступен в ближайшее время.
На данный момент этот блок не поддерживается, но мы не забыли о нём!Наша команда уже занята его разработкой, он будет доступен в ближайшее время.
На данный момент этот блок не поддерживается, но мы не забыли о нём!Наша команда уже занята его разработкой, он будет доступен в ближайшее время.
24181