Виды API — HTTP API

Несмотря на большое количество правил и рекомендаций которые описаны в спецификации HTTP, их все равно недостаточно для построения полноценного API. Есть множество вопросов, на которые HTTP не отвечает:

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

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

Как придется

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

REST

REST архитектурный стиль, который был заложен в сам HTTP (один из авторов HTTP является создателем REST). Не вдаваясь в подробности, скажем, что API построенный по этому принципу, вовсю использует возможности HTTP. Такое API активно опирается на заголовки, коды ответов, грамотно созданные эндпоинты. Например https://dummyjson.com/ построен по принципам REST. То есть, можно сказать, что глобальная идея REST в том, чтобы использовать для проектирования API возможности заложенные в HTTP изначально. Пример:

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

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

{
  "type": "photos",
  "id": "1",
  "attributes": {
    "title": "Rails is Omakase"
  },
  "relationships": {
    "author": {
      "links": {
        "self": "/photos/1/relationships/author",
        "related": "/photos/1/author"
      },
      "data": { "type": "people", "id": "9" }
    }
  }
}

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

RPC API появились в интернете практически раньше всех остальных видов API. Общая идея RPC в том, что HTTP рассматривается всего лишь как способ доставки (транспорт), но, сам по себе, не является частью 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://5b38d239-f95b-45a9-99a7-5706470b2995.mock.pstmn.io/todos/1
{
    "id": 1,
    "todo": "Do something nice for someone I care about",
    "completed": true,
    "userId": 26
}

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

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

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

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