Зарегистрируйтесь для доступа к 15+ бесплатным курсам по программированию с тренажером

Виды API HTTP API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Метод URL Операция
GET /users Список пользователей
GET /users/:id Информация о пользователе
POST /users Добавление пользователя
PATCH /users/:id Обновление пользователя
DELETE /users/:id Удаление пользователя

Однако 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 RPC versus REST


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

При разработке приложения с чужим 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

Аватары экспертов Хекслета

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

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

Для полного доступа к курсу нужен базовый план

Базовый план откроет полный доступ ко всем курсам, упражнениям и урокам Хекслета, проектам и пожизненный доступ к теории пройденных уроков. Подписку можно отменить в любой момент.

Получить доступ
1000
упражнений
2000+
часов теории
3200
тестов

Открыть доступ

Курсы программирования для новичков и опытных разработчиков. Начните обучение бесплатно

  • 130 курсов, 2000+ часов теории
  • 1000 практических заданий в браузере
  • 360 000 студентов
Отправляя форму, вы принимаете «Соглашение об обработке персональных данных» и условия «Оферты», а также соглашаетесь с «Условиями использования»

Наши выпускники работают в компаниях:

Логотип компании Альфа Банк
Логотип компании Aviasales
Логотип компании Yandex
Логотип компании Tinkoff
Рекомендуемые программы
профессия
от 25 000 ₸ в месяц
Разработка фронтенд-компонентов для веб-приложений
10 месяцев
с нуля
Старт 28 ноября
профессия
от 25 000 ₸ в месяц
Разработка веб-приложений на Django
10 месяцев
с нуля
Старт 28 ноября
профессия
от 14 960 ₸ в месяц
Ручное тестирование веб-приложений
4 месяца
с нуля
Старт 28 ноября
профессия
от 25 000 ₸ в месяц
Разработка приложений на языке Java
10 месяцев
с нуля
Старт 28 ноября
профессия
от 25 000 ₸ в месяц
Разработка веб-приложений на Laravel
10 месяцев
с нуля
Старт 28 ноября
профессия
от 39 525 ₸ в месяц
Разработка фронтенд- и бэкенд-компонентов для веб-приложений
16 месяцев
с нуля
Старт 28 ноября
профессия
от 25 000 ₸ в месяц
Разработка бэкенд-компонентов для веб-приложений
10 месяцев
с нуля
Старт 28 ноября
профессия
новый
Автоматизированное тестирование веб-приложений на JavaScript
8 месяцев
c опытом
Старт 28 ноября

Используйте Хекслет по-максимуму!

  • Задавайте вопросы по уроку
  • Проверяйте знания в квизах
  • Проходите практику прямо в браузере
  • Отслеживайте свой прогресс

Зарегистрируйтесь или войдите в свой аккаунт

Отправляя форму, вы принимаете «Соглашение об обработке персональных данных» и условия «Оферты», а также соглашаетесь с «Условиями использования»