Документация провайдера

1. 1Создайте API: имя, короткое имя в адресе, адрес вашего апстрима, таймаут, видимость.
2. 2Загрузите спецификацию OpenAPI 3. Из неё берётся всё: список операций, мок, песочница, фрагменты кода, SDK и сравнение версий.
3. 3Назначьте тарифы.
4. 4Опубликуйте. До публикации API виден только вам.

Мастер можно бросить на любом шаге и вернуться позже: черновик остаётся, ссылка на него есть в консоли провайдера. Незаконченный API не показывается никому и ничего не стоит.

• Спецификация разбирается без обращений по внешним ссылкам: $ref внутри документа работают, ссылки на чужие адреса — нет. Скачивать по ссылке из чужого файла значит ходить в сеть от нашего имени по чужому указанию.
• Короткое имя API становится первым сегментом пути: /v1/ваше-имя/…. Менять его после публикации нельзя — это сломало бы всех, кто уже вызывает.
• Мок отвечает примерами из спецификации. Чем подробнее примеры, тем полезнее песочница: путь от «нашёл API» до первого ответа — это то, где вас выбирают или не выбирают.

Тело и строка запроса передаются без изменений, включая исходное кодирование пути: перекодировать то, что клиент уже экранировал, значит молча изменить запрос, который вы получите.

Модель выводится из видимости, и отдельно её не выбирают. Решение открытое и с симметричной ценой: ушли из публичного каталога — потеряли витрину, начали платить за инфраструктуру. Значения по умолчанию у денежного поля нет нигде: однажды такое умолчание сделало расчёт холостым, и обнаружилось это только на прогоне в миллион вызовов.

• Доступ партнёру выдаётся по короткому имени его организации и сопровождается заметкой — через полгода по ней вспомнят, за что он выдан.
• Отзыв доступа гасит подписки партнёра сразу. Гасит, а не удаляет: всё, что он уже отработал, останется в счёте. Иначе отзыв был бы способом не выставлять счёт.
• Смена видимости с публичной на партнёрскую не отбирает доступ у тех, кто уже подписан: это решение о витрине, а не о действующих договорённостях.

При загрузке новой версии мы сравниваем её с предыдущей по смыслу, а не по тексту: переписанное описание, другой порядок ключей и переформатирование изменением не считаются.

• Ломающее изменение требует новой мажорной версии. Выпуск под минорной отклоняется с перечислением того, что именно сломается, — не общим «есть несовместимости».
• Changelog собирается из сравнения, если вы не написали его сами. Написанное руками мы не трогаем.
• Подписчикам уходит отдельное событие о поломке, а не признак внутри «вышла версия»: событие, которое надо разворачивать, чтобы понять его важность, читают вполглаза.
• Сравнение двух любых версий доступно и потребителю на странице API — он видит то же, что вы, и до перехода, а не после.

• Правка тарифа не меняет условия задним числом: у тарифа есть версии, и период считается по той, что действовала.
• Смена тарифа посреди месяца делит абонплату и квоту по дням.
• Бесплатный тариф — обычный тариф с нулевой ценой. Он же ваш главный инструмент: в кабинете видно, сколько потребителей перешло с него на платный.
• Тариф, на который есть подписки, нельзя удалить — только скрыть от новых подписок.

Захват заголовков и тел выключен по умолчанию и включается вами. Это единственное место, где «выключено» и есть правильное умолчание: включённый захват означал бы, что площадка начала хранить данные ваших клиентов, никого не спросив.

• Заголовки авторизации вырезаются всегда. Свои чувствительные поля перечислите отдельно — они не попадут в запись вовсе, а не будут замазаны при показе.
• Записывается выборка успешных вызовов и все ошибочные: отлаживают именно неудачные.
• Тела сжимаются и шифруются, именно в таком порядке: шифротекст неотличим от случайных байтов, а те не сжимаются.
• Срок хранения задаётся вами, в тарифе: от часа до года, по умолчанию час. Это условие тарифа, а не настройка отладки — от него зависит и то, за что платит потребитель, и то, сколько данных ваших клиентов лежит у нас. Правка срока рождает новую версию тарифа, а действующие подписки остаются на прежней.

curl 'https://apihub.tw1.su/v1/ваш-api/метод' \
  -H 'X-API-Key: ahk_test_…' \
  -H 'X-Sandbox-Chaos: latency=2000,error=503,rate=0.3'

Заголовок действует только на моках — на тестовых ключах и анонимных пробах. Подмешивать ошибки в настоящий трафик нельзя никому: это был бы способ вредить.

Площадка умеет отдавать повторный ответ из памяти, не тревожа ваш апстрим. Кэшируемость объявляете вы, в самой спецификации: мы не угадываем, что у вас меняется раз в сутки, а что каждую секунду.

/lookup:
  get:
    x-apihub-cache:
      ttl: 86400        # сколько секунд ответ можно отдавать повторно
      vary: [code]      # по каким параметрам строится ключ

• Без объявления не кэшируется ничего. Два соседних пути одного сервиса ведут себя по-разному, и по виду ответа их не различить: справочник живёт сутками, «сколько сейчас времени» не живёт вовсе.
• Кэшируется только GET и только ответ 200. Заголовок Cache-Control: no-store, no-cache или private в вашем ответе отменяет кэширование этого конкретного ответа: объявление — про операцию вообще, заголовок — про этот раз.
• Без vary в ключ идут все параметры запроса. Лишний параметр в ключе даёт лишний промах, недостающий — чужой ответ; умолчание ошибается в безопасную сторону.
• Ключ общий для всех потребителей — в этом и смысл. Поэтому кэшируемым объявляйте только то, что одинаково для всех: ответ, зависящий от вызывающего, объявлять нельзя.
• Выпуск новой версии обесценивает кэш сам: версия входит в ключ, и старые ответы просто перестают находиться.
• Попадание помечено заголовком X-Apihub-Cache: hit — и у потребителя, и в трассе.

Площадка проксирует Server-Sent Events и WebSocket. У таких вызовов нет ответа, который когда-нибудь кончится, и почти всё, на чём держится обычный путь, к ним неприменимо — поэтому и правила у них свои.

• Минуты считаются по ходу соединения, а не в конце: соединение на четыре часа, посчитанное в момент разрыва, теряется целиком при перезапуске шлюза. Первая минута начисляется сразу — минута начата, минута оплачена.
• Само соединение тарифицируемым вызовом не является: за него платят минутами, иначе час потока стоил бы минуты плюс вызов сверху.
• Квоту в вызовах минуты не расходуют. Час соединения — это не шестьдесят запросов.
• В отличие от попадания в кэш минуты делятся с вами как обычный вызов: соединение обслуживает ваш сервис, работа настоящая.
• Число одновременных соединений на подписку ограничено. Открытое соединение занимает память и дескриптор, и один потребитель с циклом переподключения иначе занимает шлюз целиком.

Площадка сама проверяет ваш API пробами и показывает результат отдельным разделом, рядом с общей статистикой, но не смешиваясь с ней: одно — то, что видели пользователи, другое — то, что видели мы. Скрыть этот раздел нельзя, иначе он не значил бы ничего.

• Путь пробы берётся из спецификации: первая операция без обязательных параметров. Если такой нет, задайте путь сами — выдумывать значения за вас мы не станем.
• Ответы 4xx считаются признаком работающего сервиса: 401 у API с авторизацией — это ответ, а не отказ.
• «Данных мало» — отдельный статус, а не пустое место: молчание читалось бы как «плохо».
• Наблюдение можно обнулить, но только при выпуске новой версии. Факт выпуска мы видим сами, верить на слово не нужно, а число сбросов показывается рядом с показателем.
• Бейдж для README отдаётся картинкой и кэшируется на пять минут.

Каталог можно показывать под своим именем: api.вашакомпания.ru вместо страницы внутри площадки. Порядок повторяет порядок в жизни: заявить домен, опубликовать TXT-запись, подтвердить.

• Кнопка подтверждения не прячется до появления записи в DNS: когда ваша зона обновилась, знаете вы, а не мы.
• Название, логотип и основной цвет задаются там же. Пустое значение означает «берите оформление площадки», а не пустоту.
• Автовыпуск сертификата на домены провайдеров пока не сделан — это записанный долг, и мы говорим об этом до того, как вы настроите DNS.

Три разных действия, и путать их дорого: у каждого своя судьба тех, кто уже подписан.

Позвать сотрудника — на экране «Сотрудники»: адрес и роль, дальше вы передаёте ссылку сами. Приглашение именное и работает только у того, кто вошёл под указанным адресом; подробности — в документации потребителя, раздел про приложения и роли: механизм общий для обеих сторон.

• Вам платят за вызовы, которые обслужил ваш апстрим. Отказ на нашей стороне, ваша же пятисотка, таймаут и ответ из мока не тарифицируются.
• Ошибка в запросе потребителя (4xx от вас) тарифицируется: вы её обработали.
• Расчёт помесячный и только после того, как сошлась сверка. Не сошлась — ничего не выставляется, пока не разберёмся.
• Выплата разделена на намерение и факт: подготовленная выплата не двигает книгу, проводка появляется, когда деньги ушли и есть номер поручения.
• Комиссия площадки видна рядом с заработанным. Показать доход без неё значило бы разойтись с тем, что вы увидите у себя в выручке, и объясняться потом.
• В кабинете виден доход по дням, топ-потребители и переход с бесплатного тарифа на платный.

1. 1Спецификация содержит примеры ответов у основных операций: по ним работают мок и песочница, а это первое, что увидит потребитель.
2. 2Есть операция без обязательных параметров — или задан путь пробы вручную, иначе наблюдение не запустится.
3. 3Таймаут выставлен по вашему настоящему времени ответа, а не «на всякий случай побольше»: он определяет, когда вызов перестанет тарифицироваться.
4. 4Бесплатный тариф решён осознанно: с ним пробуют, без него уходят к тому, у кого он есть.
5. 5Чувствительные поля перечислены в настройках захвата — до того, как захват включён, а не после.
6. 6Апстрим доступен снаружи и не ограничен по адресу так, что наш шлюз в него не попадёт.