Виды 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.

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

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"
}

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

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

---

Остались вопросы? Задайте их в разделе «Обсуждение»

Вам ответят команда поддержки Хекслета или другие студенты

Об обучении на Хекслете

• Статья «Как учиться и справляться с негативными мыслями»
• Статья «Ловушки обучения»
• Статья «Сложные простые задачи по программированию»
• Вебинар «Как самостоятельно учиться»