Разработка API
для рынка США

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

Версия в адресе или в заголовке, правило совместимости описано в документации. Добавление поля считается совместимым изменением, удаление и переименование — нет. Новая версия живёт рядом со старой, и срок поддержки старой объявляется числом месяцев. Без этого правила первое же изменение ломает интеграции партнёров.

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

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

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

Скользящее окно по ключу, отдельные лимиты на тяжёлые методы. При превышении возвращаем код 429 и заголовок со временем до сброса. Лимит подбираем по реальному профилю нагрузки. Без лимитов один клиент с ошибкой в цикле роняет сервис остальным.

Событие уходит с подписью, чтобы получатель проверил источник. Доставка повторяется по возрастающему интервалу, пока не придёт подтверждение. Журнал показывает попытки и коды ответа, а клиент может перезапросить пропущенные события сам. Так пропавшее событие перестаёт быть спором.

Спецификация OpenAPI как источник правды, примеры запросов и ответов, коды ошибок с расшифровкой, описание лимитов и версий. Плюс тестовая среда с готовыми данными и ключом, который выдаётся без письма в поддержку. Американский разработчик решает за десять минут, и решает по документации.

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

Да, и это частый сценарий. Мы делаем слой API поверх вашей базы и логики, без переписывания ядра. Сначала описываем контракт и согласуем его с потребителями, потом реализуем. Такой порядок дешевле: менять контракт на бумаге стоит часов, а после подключения клиентов — недель.

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