Rivalry2

HTML Diff

1 added 0 removed

Original 2026-01-01

Modified 2026-02-26

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

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

3 <ul><li>Данные передаются в формате JSON</li>

4 <li>Для каждого набора данных используется свой URL</li>

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

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

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

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

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

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

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

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

13 <ul><li>упаковать данные - то есть сериализовать их</li>

14 <li>извлечь данные - десериализовать их</li>

15 </ul>Задача сериализации и десериализации возникает тогда, когда нам нужно передать данные из программы наружу - например, другим программам.

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

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

18 <ul><li>Сервис, который предоставляет HTTP API, извлекает данные из хранилища, формирует JSON и отдает его наружу</li>

19 <li>Затем этот JSON может прочитать любая программа с поддержкой JSON (а это большинство современных программ)</li>

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

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

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

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

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

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

26 <h2>Структура JSON</h2>

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

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

29 <ul><li>1, 3, 2.5</li>

30 <li>true, false</li>

31 <li>"one", "two"</li>

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

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

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

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

36 + <h2>Метаданные</h2>

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

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

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

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

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

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

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

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

40 <h2>Пагинация</h2>

41 <h2>Пагинация</h2>

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

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

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

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

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

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

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

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

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

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

46 <h2>Ограничение данных</h2>

47 <h2>Ограничение данных</h2>

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

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

48 <h2>Одиночный ресурс</h2>

49 <h2>Одиночный ресурс</h2>

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

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

50 .

51 .

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

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

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

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

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

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

54 <h2>Вложенные ресурсы</h2>

55 <h2>Вложенные ресурсы</h2>

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

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

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

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

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

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

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

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

59 <h2>Выводы</h2>

60 <h2>Выводы</h2>

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

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