Запросы на сервер (fetch), взаимодействие с backend api, использование swagger.

В этом уроке, посмотрим на backend глазами frontend разработчика и узнаем каким образом с ним взаимодействовать.

Для взаимодействия с API в данном уроке, мы будем использовать Swagger — инструмент для интерактивной документации, который позволяет изучать эндпоинты, тестировать запросы и анализировать структуру ответов. Выполним отправку запросов следующим образом:

• через интерфейс Swagger,
• с помощью консольной утилиты curl,
• посредством нативного метода fetch в браузере,
• проанализируем структуру запросов (url, headers) и ответов (JSON).
• используем уникальный API key, который необходимо будет передавать в заголовках каждого запроса для аутентификации приложения.

Основы архитектуры клиент-серверного взаимодействия. Роли frontend и backend.

• Frontend

Относится к клиентской части приложения, с которой непосредственно взаимодействует пользователь. Основная задача которой — отправлять запросы на backend, получать данные и визуализировать их для пользователя.

• Backend

Серверная часть приложения, которая обрабатывает запросы от frontend. Выполняет бизнес-логику, например, взаимодействует с базой данных, формирует и отправляет ответы. Backend может быть написан на различных языках программирования (Node.js, Python, Go, PHP и др.).

Frontend, как правило, делает запросы на backend, получает какие-то данные и эти данные визуализирует.

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

Процесс сборки и запуска frontend приложения

1. Мы имеем React проект, который, как правило, состоит из файлов (.jsx, .tsx), хранящихся на диске разработчика.
2. Проект мы создали с помощью такого инстумента как Vite, который используется для компиляции, транспиляции и сборки исходных файлов в формат, понятный браузеру (HTML, JavaScript, CSS). Это происходит, например, по команде npm run dev.
3. Vite запускает локальный dev-сервер (например, на порту localhost:5173), который раздает статичные файлы собранного приложения.
4. Пользователь открывает адрес в браузере. Браузер отправляет первый запрос на локальный сервер и получает index.html файл.
5. В случае с SPA - single page application, полученный нами HTML-файл обычно содержит пустой div с идентификатором root и тег <script>, который инициирует второй запрос для загрузки JavaScript-кода.
6. После загрузки JavaScript в оперативной памяти вкладки браузера React "оживляет" страницу, отрисовывая компоненты внутри div с id='root'.
7. И только после инициализации, frontend приложение отправляет запросы на удаленный backend сервер для получения динамических данных.

Взаимодействие между клиентом и сервером происходит по протоколу HTTP или его защищенной версии HTTPS.

• HTTPS: обеспечивает безопасное (шифрованное) соединение, что критически важно при передаче данных через интернет. По умолчанию использует порт 443.
• URL: уникальный адрес, состоящий из протокола (HTTPS), домена и, опционально, порта.

API как интерфейс взаимодействия с backend.

API (Application Programming Interface) — это программный интерфейс описывающий, каким образом одна программа должна взаимодействовать с другой.

API определяет:

• Доступные адреса (endpoints).
• Форматы запросов (request) и ответов (response).
• Методы аутентификации.
• Параметры для фильтрации, сортировки и т.д.

Swagger — это популярный инструмент для создания интерактивной API-документации.

Swagger представляет собой интерактивное frontend приложение, которое не только описывает endpoint, но и позволяет отправлять тестовые запросы к API. Как правило, документация Swagger, генерируется автоматически на основании кодовой базы backend.

Однако, существует подход API First, при котором, сначала создается документация (спецификация), а затем frontend и backend разработчики пишут код, который ей соответствует.

Endpoint — представляет собой конкретный URL адрес, по которому требуется обратиться для выполнения операции над определенным ресурсом (например, получение списка треков, создание плейлиста). Каждый endpoint представлен в документации отдельным элементом, нажав на который можно увидеть описание его назначения и параметры.

Взаимодействие с API Music Fun.

Регистрация и получение API-ключа:

1. Необходимо зарегистрироваться или авторизоваться на платформе-провайдере API, в нашем случае это https://apihub.it-incubator.io/.
2. После авторизации для аккаунта автоматически генерируется уникальный API Key.
3. Если ваш API-key скомпрометирован (например, попал в публичный github репозиторий), необходимо сгенерировать новый.

Тестирование API с использованием UI Swagger.

Поскольку интерфейс Swagger позволяет выполнять тестовые запросы. Сделаем это! Для этого нам потребуется выполнить следующие шаги:

1. Выбрать интересующий вас эндпоинт (например, GET /public/tracks для получения списка треков).
2. Нажать кнопку Try it out, чтобы активировать форму для отправки запроса.
3. Нажать кнопку Execute.
4. Получим ошибку 429 (Too Many Requests) с сообщением The domain is incorrect. Check your API settings.. Потому что выполнили запрос без использования api-key.

Аутентификация запросов с помощью api-key

Чтобы запрос был успешным, необходимо передать api-key. В Swagger это можно сделать двумя способами:

• Локально: Сделать это можно для конкретного запроса, нажав на икону замка в правой части и ввести ключ.
• Глобально: Ввести ключ глобально нажав кнопку Authorize и добавить в соответствующее поле (api-key), после чего он будет автоматически добавляться ко всем последующим запросам в текущей сессии.

Повторное выполнение запроса после авторизации вернет успешный ответ со статусом 200 OK и телом ответа в формате JSON.

Ответ от сервера приходит в формате JSON (JavaScript Object Notation). У нашего запроса к endpoint GET /public/tracks, структура ответа следующая:

• Объект data.
  • Свойство data, которое представляет собой массив, где каждый элемент — это объект, представляющий один трек.
  • Объект трека, который содержит ключевые поля:
    • id: уникальный идентификатор.
    • attributes: объект с основными характеристиками.
    • title: название трека.
    • attachments: массив с файлами. Обычно содержит один объект.
      • В массиве attachments лежит объект, который имеет свойство url, содержащее прямую ссылку на аудиофайл (MP3).

Анализ сетевых запросов в браузере при помощи инструментов разработчика

Вкладка Network в инструментах разработчика браузера позволяет отслеживать все сетевые запросы, отправляемые страницей.

1. Можно отфильтровать запросы по типу, например, Fetch/XHR, чтобы видеть только асинхронные API-запросы.

2. Кликнув на запрос, во вкладке Headers можно изучить его детали: url, method, headers, body и т. д.

3. Во вкладке Response можно увидеть "сырой" ответ сервера

4. Во вкладке Preview — отформатированное дерево JSON-объекта, которое удобно анализировать

Выполнение запросов с помощью JavaScript

Запросы к API можно отправлять напрямую используя встроенный в Javascript метод fetch, который работает на основе Promises.

const promise = fetch("https://musicfun.it-incubator.app/api/1.0/playlists/tracks", {
  headers: {
    "api-key": "ВАШ API-KEY",
  },
})
const json = promise.then((res) => res.json()) // Преобразование ответа в JSON
json.then((data) => console.log(data)) // Получение всего объекта данных приходящего с сервера

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

Получим название трэка:

json.then((data) => {
  // Работа с полученными данными (json)
  console.log(data[0].attributes.title) // Вывод названия первого трека
  console.log(data[0].attributes.attachments[0].url) // Вывод URL первого трека
})
const promise = fetch("https://musicfun.it-incubator.app/api/1.0/playlists/tracks", {
  headers: {
    "api-key": "ВАШ API-KEY",
  },
})
const json = promise.then((res) => res.json())
json.then((data) => {
  // Работа с полученными данными (json)
  console.log(data.data[0].attributes.title) // Вывод названия первого трека
})

В консоли вы должны увидеть gangsta react.

Использование терминала для запросов

Swagger предоставляет готовую curl-команду для выполнения запроса из терминала, которая включает в себя url endpoint и headers (-H).

• Accept: application/json: Сообщает серверу, что клиент ожидает ответ в формате JSON.
• API-KEY: Заголовок с вашим секретным ключом.
• Прямой запрос через curl может быть заблокирован из-за проверки домена. Чтобы обойти это, нужно добавить заголовок Origin, имитирующий запрос с разрешенного домена: -H "Origin: http://localhost".
• Для удобного просмотра JSON-ответа в терминале можно использовать конвейер (pipe |) и утилиту-форматтер, например jq.

Необходимый код:

curl -X 'GET' \
  'https://musicfun.it-incubator.app/api/1.0/playlists/tracks?pageNumber=1&pageSize=20&sortBy=publishedAt&sortDirection=desc&paginationType=offset' \
  -H 'accept: application/json' \
  -H 'api-key: ВАШ API-KEY' \
  -H 'origin: http://localhost' | jq

Результат выполнения 🚀

🏠 Домашнее задание

Цель задания:

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

API для работы

Задание 1

Регистрация и получение API ключа

1. Зарегистрируйтесь в apihub (если требуется)
2. Откройте Trelly API
3. Получите свой API ключ.

Задание 2

Авторизация в Swagger

1. Перейдите в swagger документацию
2. Нажмите на кнопку "🔒 Authorize" в Swagger UI
3. Введите свой API ключ в открывшемся модальном окне

Задание 3

Получение списка задач (тасок) через Swagger UI

1. Откройте endpoint для получения всех тасок
2. Сделайте запрос за получением задач. "Try it out" → "Execute"

Если в разделе responses(ответ с сервера) вы получили ответ со следующей структурой, значит вы все сделали правильно 🚀

{
  "data": [
    {
      "id": "07b51554-f680-4b5f-8e81-dbcbe32d08cc",
      "type": "tasks",
      "attributes": {
        "title": "html",
        "boardId": "e11c9480-dd73-4b08-a5fd-452465467805",
        "status": 0,
        "priority": 1,
        "addedAt": "2025-08-27T17:51:48.031Z",
        "attachmentsCount": 0
      }
    }
    /*...*/
  ],
  "meta": {
    "page": 1,
    "pageSize": 10,
    "totalCount": 4,
    "pagesCount": 1
  }
}

Задание 4

Запрос через консоль браузера

Выполните GET запрос для получения списка задач через консоль браузера:

fetch("https://trelly.it-incubator.app/api/1.0/boards/tasks", {
  headers: {
    "api-key": "YOUR_API_KEY", // ❗ Замените на свой ключ
  },
})
  .then((response) => response.json())
  .then((data) => {
    console.log("Список задач", data)
  })

Итоговый результат 🚀

Задание 5 ⭐

⭐ Дополнительное задание со звездочкой. Проделывать по желанию.

Задание 5.1

Curl запросы

Выполните запрос через командную строку

curl -X 'GET' \
  'https://trelly.it-incubator.app/api/1.0/boards/tasks?pageNumber=1&pageSize=10' \
  -H 'accept: application/json' \
  -H 'api-key: YOUR_API_KEY' \
  -H 'origin: http://localhost'

Итоговый результат 🚀

Задание 5.2

Анализ сетевых запросов

1. Откройте Developer Tools (F12)
2. Перейдите на вкладку Network
3. Выполните запрос за тасками через Swagger UI
4. Найдите этот запрос в Network tab и изучите:

• Какие заголовки (headers) отправляются?
• Какой URL используется?
• Что приходит в ответе?

Важные напоминания

⚠️ Безопасность:

• Никогда не делитесь своим API ключом
• Не публикуйте API ключи в открытых репозиториях
• Если случайно "засветили" ключ - перегенерируйте новый

⚠️ Лимиты запросов:

• Не делайте слишком много запросов подряд
• Следите за лимитами API
• При ошибках внимательно читайте сообщения об ошибках