cURL Basics — документация К тестеру

Базовая модель запроса cURL

Текст термина (дословно из источника)

Базовая модель запроса - это минимальная структура, по которой строится любой вызов внешнего API.

Простыми словами: нужно определить "куда", "что делаем", "с какими правами" и "какие данные передаем".

При работе со сторонним API - читайте документацию.

Общий вид: [https|http]://[url|ip]:[port]/[endpoint]?[query]

Универсальная модель:

  • Протокол [https|http];
  • хост API [url|ip];
  • порт API [port];
  • endpoint [endpoint];
  • HTTP-метод;
  • обязательные заголовки;
  • query-параметры [query] и/или body;
  • интерпретация ответа.

Из них обязательны только протокол [https|http] и адрес[url|ip].

Остальные обязательные поля описываются разработчиками API в документации.

Подробнее:

  1. Протокол, хост и порт API
  • Узел в сети куда будут уходить запросы. Чаще всего с указанием протокола (HTTP/HTTPS) и порта. При указании https данные будет запрос действующего сертификата. Эти данные предоставляются разработчиком API.
  1. Endpoint
  • Конкретный путь API для операции.
  • Примеры Метрики:
  • /management/v1/counters
  • /stat/v1/data
  • /management/v1/counter/{counterId}/goals
  1. Метод
  • Определяет действие (GET, POST, PUT/PATCH, DELETE).
  • В типовых сценариях Метрики на старте чаще используется GET для чтения.
  1. Заголовки
  • Передают доступ и формат.
  • Для Метрики базовый минимум:
  • Authorization: OAuth <token>
  • Accept: application/json
  1. Query-параметры
  • Чаще всего используются в GET запросах, после ? знака в URL
  • например: GET /stat/v1/data?ids=<counter_id>&metrics=ym:s:visits&date1=today-7&date2=today
  • Передают фильтры, периоды, метрики, пагинацию.
  • Для отчета в Метрике обычно задают:
  • ids, metrics, date1, date2
  • Дополнительно по сценарию: dimensions, filters, limit, offset.
  1. Тело запроса (body)
  • Используется не во всех endpoint; чаще требуется для операций изменения.
  • При наличии body формат должен быть согласован с Content-Type.

На примере API Яндекс.Метрики:

  • хост: https://api-metrika.yandex.net;
  • пример чтения списка объектов:
  • GET /management/v1/counters
  • пример чтения отчетных данных:
  • GET /stat/v1/data?ids=<counter_id>&metrics=ym:s:visits&date1=today-7&date2=today
  • заголовок доступа:
  • Authorization: OAuth <token>

Практический вывод:

  • Единая модель запроса снижает вариативность и количество ошибок при интеграции.
  • Для Метрики полезно иметь канонический шаблон "auth + endpoint + параметры отчета".