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

Виды 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 изначально. Пример:

Метод Маршрут Описание
GET /photos список фотографий
POST /photos создание фотографии
GET /photos/:id данные фотографии
PATCH/PUT /photos/:id обновление фотографии
DELETE /photos/:id удаление фотографии

Однако, 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.


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

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

  1. Для создания Mock сервера вам необходима коллекция API. Создайте её, если её еще нет. Например коллекцию для Todos

  2. Следуя документации создайте Mock сервер для созданной ранее коллекци.

  3. Выполните запросы к созданному серверу (через браузер или curl). Пример запроса и ответа:

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
}

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


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

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

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

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

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

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

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

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

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

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

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

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

Логотип компании Альфа Банк
Логотип компании Aviasales
Логотип компании Yandex
Логотип компании Tinkoff
Рекомендуемые программы

С нуля до разработчика. Возвращаем деньги, если не удалось найти работу.

Иконка программы Фронтенд-разработчик
Профессия
Разработка фронтенд-компонентов веб-приложений
30 июня 10 месяцев
Иконка программы Python-разработчик
Профессия
Разработка веб-приложений на Django
30 июня 10 месяцев
Иконка программы PHP-разработчик
Профессия
Разработка веб-приложений на Laravel
30 июня 10 месяцев
Иконка программы Node.js-разработчик
Профессия
Разработка бэкенд-компонентов веб-приложений
30 июня 10 месяцев
Иконка программы Fullstack-разработчик
Профессия
Новый
Разработка фронтенд и бэкенд компонентов веб-приложений
30 июня 16 месяцев
Иконка программы Java-разработчик
Профессия
Разработка приложений на языке Java
30 июня 10 месяцев

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

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

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

Даю согласие на обработку персональных данных, соглашаюсь с «Политикой конфиденциальности» и «Условиями оказания услуг»

Изображение Тото

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