Виды API — HTTP API

• API по принципу «как придется»
• Архитектурный стиль REST
• Удаленный вызов процедур (Remote Procedure Call, RPC)

В спецификации HTTP есть много правил и рекомендаций, но их все равно недостаточно для построения полноценного API.

Есть множество вопросов, на которые спецификация HTTP не отвечает:

• Как строить URL?
• Как работать с ошибками?
• В каком формате и какой структуры возвращать данные?
• Как делать пагинацию?

Именно поэтому для построения хорошего API недостаточно правил HTTP. Нужны дополнительные соглашения, которые мы изучим в этом уроке.

За время существования интернета было создано немало стандартов API. Среди них можно выделить несколько больших направлений, которые строятся по примерно одинаковым правилам.

Ниже мы рассмотрим их подробнее, а пока просто познакомимся с ними:

API по принципу «как придется»

Сюда попадают все API, которые делают по принципу «как получится». Обычно они встречаются во внутренних сервисах или публичных старых сервисах, созданных десятки лет назад.

Здесь нет никаких правил:

• каждый эндпоинт существует сам по себе
• активно используются параметры запроса
• игнорируются коды ответа и другие возможности самого HTTP

В теории такие API делать не стоит, но на практике они иногда встречаются.

Архитектурный стиль REST

REST — это архитектурный стиль, который был заложен в сам протокол HTTP, ведь его придумал один из создателей HTTP.

API, построенный по этому принципу, вовсю использует возможности HTTP. Такое API активно опирается на заголовки, коды ответов, грамотно созданные эндпоинты. Например, Example Api построен по принципам REST.

Можно сказать, что глобальная идея REST — использовать для проектирования API возможности, заложенные в HTTP изначально:

Однако REST не отвечает на те вопросы из начала урока. REST — это архитектурный стиль, а не конкретный стандарт. В эндпоинтах выше мы видим адреса и методы HTTP, но мы не знаем, какими будут данные в запросах и в ответах. Поэтому любое REST API имеет свои особенности, которые присущи только ему — у него есть свой способ обработки ошибок и своя структура возвращаемых данных.

Разработчики пытаются создать стандарт, который добавляет в REST все недостающие части. Самый удачный пример — json:api. Этот стандарт описывает конкретные структуры данных для разных типов запросов и ответов. Так может выглядеть извлечение конкретного пользователя:

{
  "id": "1",
  "email": "max@yahoo.com",
  "firstName": "Max",
  "lastName": "Maxwell"
}

Удаленный вызов процедур (Remote Procedure Call, RPC)

RPC API появились в интернете практически раньше всех остальных видов API. Здесь HTTP рассматривается как способ доставки API, но сам по себе не является частью API.

Как правило, RPC API работают с одним эндпоинтом — например, /rpc, на который отправляется GET или POST. RPC API используют небольшое количество заголовков и кодов ответов. Обработка ошибок, выполнение разных действий — все это в RPC зашито в само тело запроса и ответа.

Идея RPC в том, что мы просто вызываем обычные функции, а они каким-то магическим образом делают запросы на внешнюю систему, полностью или почти полностью скрывая от нас существование HTTP и сети в целом.

Запрос в JSON-RPC выглядит как JSON, в котором указывается, какую функцию и с какими параметрами нужно вызвать:

{
  "jsonrpc": "2.0",
  "method": "subtract",
  "params": { "minuend": 42, "subtrahend": 23 },
  "id": 3
}

В ответе приходит результат вызова этой функции:

{
  "jsonrpc": "2.0", "result": 19, "id": 3
}

Разновидностей RPC очень много, и они сильно отличаются между собой. Из наиболее известных можно назвать NFS, SOAP, XML-RPC, JSON-RPC, gRPC, GraphQL.

Самостоятельная работа

При разработке приложения с чужим API часто нужно проверять, точно ли приложение работает и выполняет запросы. Это может быть и клиентское фронтенд-приложение, и серверное бэкенд-приложение, которое обращается на внешний сервис. Для разработки и тестирования есть различные инструменты, которые позволяют создавать заглушки вместо реального приложения с API. Такую возможность предоставляет и Postman, в котором можно создать mock-сервер, который отдает готовый ответ на указанные запросы.

1. Для создания mock-сервера нужна коллекция API. Создайте ее самостоятельно или используйте коллекцию для Tasks
2. Изучите документацию и создайте mock-server для созданной ранее коллекции
3. Выполните запросы к созданному серверу через браузер или curl. Можете ориентироваться на такой пример запроса и ответа:

curl -X GET https://http.hexlet.app/http-api/tasks/c7c2fa01-3174-4cc4-9a80-092b47ade67d
{
  "id": "c7c2fa01-3174-4cc4-9a80-092b47ade67d",
  "title": "Опубликовать курс по основам JavaScript",
  "description": "Автор подготовил курс по JavaScript. Нужно его опубликовать",
  "status": "Backlog"
}

В результате вы создадите mock-сервер для коллекции Postman. Сервер на все запросы будет отвечать заготовленными ранее ответами. Адрес созданного сервера будет доступен публично.

Дополнительные материалы

1. Что такое REST?
2. Что такое GraphQL