Developer

Как найти API: документация, Swagger UI, DevTools, коллекции

↑ 1.1 Что такое API и как устроены системы · ← Предыдущая

Обязательно~7 мин чтенияУровень: junior

Зачем это аналитику и PM

Описание метода редко лежит одним файлом. Нужно найти контракт, отличить его от фактического запроса экрана и понять, у кого просить доступ, иначе переписка «пришлите ещё раз тот JSON» растягивается на дни.

План темы

  • где искать описание
  • публичные коллекции Postman
  • как понять, какие запросы делает приложение
  • к кому идти за доступом

Объяснение

Найти API — собрать проверяемые сведения о методе: адрес, поля, пример ответа, стенд и того, кто имеет право контракт менять. Берут тот источник, который команда считает правдой.

Как расписание поликлиники. На сайте одна таблица, в регистратуре другая, табло показывает фактический приём. Документация, Swagger UI и запрос браузера — три таких источника.

Где искать описание

Начните со ссылки автора задачи: страница в базе знаний или файл спецификации. Если ссылки нет, спросите владельца сервиса. Спецификацию HTTP API часто отдают в формате OpenAPI. Swagger UI — экран поверх неё: пути, поля и пробный вызов. Словом «Swagger» называют и этот экран, и старое имя спецификации. Что прислали, видно по файлу.

ИсточникЧто взятьЧего не ждать
Страница в викиСмысл и ограничения сценарияЧто поля не устарели
Swagger UI и OpenAPIПуть, поля, пример телаМатрицу ролей и весь сценарий
Коллекция запросовПример, который уже запускалиЧто автор — владелец API
Вкладка сети в браузереФактический вызов экранаМетоды, до которых экран не доходит
Владелец сервисаСтенд и доступОтвет без имени метода

Коллекции и запросы экрана

Коллекция в Postman — папка готовых запросов. Публичные ищут по имени сервиса. Чужой файл бывает устаревшим или чужим черновиком. Смотрят издателя и сверяют один метод с официальным описанием. Импорт спецификации вашей команды надёжнее случайной коллекции.

Чтобы увидеть вызовы своего экрана, откройте тестовый стенд и панель разработчика браузера, вкладку сети. Повторите действие и отделите API от картинок. Это факт интерфейса, не каталог сервера: фоновые интеграции в браузере не появятся. Запрос можно скопировать как curl в баг, вырезав заголовок доступа и cookie. В тексте достаточно маски Bearer eyJ....

У кого просить доступ

Доступ просят у владельца сервиса или у того, кого он назвал. В письме нужны стенд, метод или сценарий, зачем доступ и на какой срок. «Дайте доступ к API» без этого возвращается встречным вопросом. Для чтения контракта боевая запись обычно не нужна.

flowchart TD
    A["Нужен контракт метода"] --> B{"Команда дала ссылку"}
    B -->|"да"| C["Читать этот документ"]
    B -->|"нет"| D["Спросить владельца сервиса"]
    C --> E["Сверить со стендом или с запросом экрана"]
    D --> E
    E --> F{"Описание есть"}
    F -->|"нет"| G["Черновик с пометкой факт экрана"]
    F -->|"да"| H["Пример в задачу и вопрос по расхождениям"]

Примеры

JSONPlaceholder вызывается без ключа. Это учебная проверка чтения, не поиск вашего внутреннего API.

curl -sS "https://jsonplaceholder.typicode.com/todos/1" -H "Accept: application/json"
{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

Схема внутреннего вызова. Хост учебный, токен закрыт. На боевой адрес эту строку не отправляют.

GET /orders/1042 HTTP/1.1
Host: test.example.com
Accept: application/json
Authorization: Bearer eyJ...

У сообщества OpenAPI есть учебный Petstore: спецификация, по которой обычно показывают Swagger UI. Адрес демонстрации менялся, берите его из документации проекта. В компании ориентир другой — страница владельца сервиса. В обоих случаях с карточки выписывают одно и то же.

метод и путь: GET /todos/1
стенд: публичный учебный JSONPlaceholder
поле для экрана: title
чего нет в примере: ошибок и прав доступа

Нюансы и подводные камни

  • Пробный вызов в Swagger UI бьёт в сервер, выбранный на странице. Случайный prod выполнит запрос по-настоящему.
  • Пустой список в ответе может быть нормой стенда, а не поломкой метода.
  • В баг не кладут сырой дамп с секретом. Нужны путь, значимые поля и код ответа.
  • Коллекция без стенда почти наверняка смотрит на чужой dev.

Практика

На JSONPlaceholder или на вашем test найдите один метод чтения. Выпишите метод, путь, одно поле и источник.

Ожидаемый результат: строка вроде «GET /todos/1, поле title, источник — публичный JSONPlaceholder» либо то же про ваш test со ссылкой для коллеги. Боевого токена рядом нет. Для внутреннего метода указан стенд, не только путь.

Вопросы с ответами

Связано с блоком Developer

Связанные темы

Вид графа

Обратные ссылки