Публичный API Foxguide

Публичный API доступен по адресу https://api.foxguide.io. Каждый запрос аутентифицируется API-токеном, и каждый токен несёт явный список областей доступа (scopes). По умолчанию не выдаётся ничего — токен достаёт только то, для чего он был выпущен.

curl https://api.foxguide.io/v1/tables \
  -H 'Authorization: Bearer fgd_live_...'

Впервые здесь? Начните с Быстрого старта — как выпускается токен и какое его свойство чаще всего застаёт врасплох (секрет показывается ровно один раз).

На какой вопрос отвечает каждый раздел

раздел	вопрос, на который он отвечает
Быстрый старт	Как получить токен и выполнить первый вызов?
Аутентификация	Что такое область доступа и почему мне отказали?
Ошибки	Какой формы ошибка и стоит ли её повторять?
Постраничная выдача	Как обойти коллекцию, не потеряв строки?
Лимиты частоты	Сколько запросов мне доступно и что означает 429?
Версионирование и вывод из эксплуатации	Что может измениться подо мной и сколько будет предупреждения?
Вебхуки	Как проверить доставку и как отправить свою?
История изменений	Что изменилось и когда?

Справочник эндпоинтов генерируется из опубликованного документа OpenAPI и является авторитетом по каждому пути, параметру и форме ответа. Сам документ лежит по адресу /openapi/public-openapi.yaml, если вам удобнее сгенерировать клиент, чем читать страницу.

Контракт работает по явному включению

Эндпоинт входит в публичный API только тогда, когда сам себя таковым объявил. Справочник и поверхность, доступная токену, генерируются из одного и того же объявления, поэтому разойтись они не могут: задокументировано ровно то, что достижимо, а маршрут, отсутствующий в справочнике, отвечает 403, а не работает незадокументированным.

Три следствия, которые стоит усвоить до начала разработки:

• Запрет по умолчанию — не фигура речи. Токен без подходящей области доступа получает отказ, и токен вообще без списка областей — тоже: отсутствующий список трактуется точно так же, как пустой.
• Аддитивные изменения выходят без уведомления. Игнорируйте незнакомые поля ответа и откатывайтесь на HTTP-статус для кода error, которого вы ещё не видели.
• Всё неаддитивное сопровождается опубликованным сроком уведомления. Шесть месяцев, объявленные в истории изменений и в двух заголовках ответа.

Пока недоступно

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