HTTP API
2026-02-26 15:08 Diff
https://ru.hexlet.io/courses/http-api/lessons/example/theory_unit

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

Обычно HTTP API построен по следующим правилам:

  • Данные передаются в формате JSON
  • Для каждого набора данных используется свой URL

Это далеко не единственный способ организации HTTP API, но один из самых распространенных.

Для примера возьмем сервис HTTP Server, созданный специально для экспериментов с API. Он включает в себя ненастоящие данные, с которыми можно попрактиковаться.

В документации сервиса описываются ресурсы — сущности, информацию о которых мы можем получать по API. Ниже их неполный список:

Каждая ссылка, по которой мы получаем какие-то данные в HTTP API, называется эндпоинтом.

Для получения списка пользователей нужно загрузить https://http.hexlet.app/http-api/users. Ее можно открыть даже в браузере. В ответ вернется такой текст:

Здесь мы работаем с ненастоящими данными. В реальном API мы бы еще подтвердили доступ, потому что нельзя отдавать такие данные всем подряд.

Формат, в котором данные передаются, называется JSON. Давайте остановимся на этом подробнее.

Формат — это способ описания данных. С ним можно работать двумя способами:

  • упаковать данные — то есть сериализовать их
  • извлечь данные — десериализовать их

Задача сериализации и десериализации возникает тогда, когда нам нужно передать данные из программы наружу — например, другим программам.

Данные внутри языков представляются каким-то способом, специфичным для данного языка и даже его конкретной версии. Поэтому для передачи данных и используются универсальные форматы, которые известны всем.

В случае HTTP API этот механизм работает так:

  • Сервис, который предоставляет HTTP API, извлекает данные из хранилища, формирует JSON и отдает его наружу
  • Затем этот JSON может прочитать любая программа с поддержкой JSON (а это большинство современных программ)

Поддержка JSON часто реализована прямо на уровне языков программирования. JSON — это всего лишь текст. У него есть понятная структура, которая прослеживается визуально. Отступы, пробелы и переносы для JSON не имеют значения.

Пример выше может выглядеть и так:

Разберемся, чем это отличается от передачи данных в HTML.

HTML — обычно служит для передачи данных в браузеры, так как это язык разметки, с помощью которого формируется текст для браузеров. Браузеры считывают HTML и отображают его в виде веб-страницы. HTML не подразумевает работу с данными, которые содержатся внутри него. Теоретически это можно сделать, но на практике будет очень сложно.

JSON — это не единственный формат данных. До него популярным форматом был XML, и сейчас он встречается довольно часто. Так выглядит XML-файл:

XML похож на HTML, но решает другую задачу. XML — это формат данных, как и JSON. Разница лишь в том, что XML не предназначен для вывода.

Структура JSON

Данные в формате JSON хранятся внутри объектов. Объект — это часть данных, ограниченная фигурными скобками, внутри которых задаются ключи и их значения:

Ключи в JSON всегда обернуты кавычками. В качестве значений могут выступать числа, булевы значения, строки и null:

  • 1, 3, 2.5
  • true, false
  • "one", "two"

Также значениями могут быть массивы:

Причем весь JSON может быть только массивом:

Объекты могут быть вложенными в другие объекты:

А еще объекты можно вложить в массивы:

Метаданные

Если посмотреть на структуру ответа /users, то становится видно, что список пользователей передается как массив внутри объекта с дополнительными параметрами:

Зачем так сделано? Почему бы сразу не отдавать массив пользователей?

Ответ здесь очень простой. Часто нужно передавать не только данные, но и метаданные — то есть данные о данных. Например, к метаданным относится общее количество пользователей. Если бы у нас был массив, то эту информацию было бы невозможно добавить без изменения структуры и перехода от массива к объекту.

Объект же позволяет добавлять новые данные, сохраняя обратную совместимость в структуре, не ломая ее. Нужно просто добавить новый ключ на верхний уровень, и все готово.

Пагинация

Иногда данных слишком много: как на Хекслете, у которого сотни тысяч пользователей. JSON с таким объемом данных получится огромным и тяжелым.

Для решения этой задачи используют пагинацию — с ней данные отдаются не целиком, а небольшими наборами. Пагинацию мы встречаем в интернете на каждом шагу. Вспомните результаты поиска в Google — поисковик находит миллионы страниц, но показываются только первые десять результатов, а остальные скрывает на других страницах.

В API, с которым мы работаем, по умолчанию отдается 30 результатов. Это видно из возвращаемого JSON:

Как в таком случае получить вторые 30 человек? Нужно добавить параметр skip: https://http.hexlet.app/http-api/users?skip=30. Так будет выглядеть JSON:

В примере с пользователями это не имеет смысла, так как пользователей всего 10. Но, например, для запроса постов полезно, так как их количество может быть больше https://http.hexlet.app/http-api/posts?skip=30:

Ограничение данных

Представим, что нам нужны не все данные, а только их часть. Для этого в нашем HTTP API есть параметр запроса select: https://http.hexlet.app/http-api/users?select=firstName,email. Так он выглядит:

Одиночный ресурс

Эндпоинт /users возвращает список пользователей. Если нам нужен один пользователь, то для этого понадобится другой эндпоинт — /users/

.

Этот эндпоинт называется динамическим, потому что у него есть меняющаяся часть. Вместо

подставляется идентификатор конкретного пользователя, данные которого мы хотим получить.

Возьмем для примера https://http.hexlet.app/http-api/users/1 и посмотрим на результат:

Вложенные ресурсы

Часто пользователи могут писать посты на сайте. Если мы захотим увидеть весь список постов, то используем эндпоинт /posts.

Чтобы увидеть посты конкретного пользователя, мы воспользуемся вложенными ресурсами: https://http.hexlet.app/http-api/users/1/posts.

Этот эндпоинт вернет все посты пользователя с идентификатором 1:

По такому же принципу устроена работа со всеми остальными ресурсами:

Выводы

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