Публичное API SaaS: что подготовить для первого партнёра
Для запуска публичного API SaaS подготовьте один завершённый сценарий внешнего партнёра: получение доступа, выполнение операции, проверку результата и обращение за помощью. Опубликовать внутренние методы или сгенерировать список адресов недостаточно. Партнёр должен понимать свои полномочия, ограничения и последствия повторного запроса до подключения реальных данных.
Выберите действие, ради которого подключаются
Начните с разговора о результате, а не о количестве методов. Например, в учебном сервисе партнёр передаёт заявку из своей системы и получает её текущий статус. Для этого ему нужны понятный формат заявки, подтверждение принятия и способ узнать итог. Экспорт всей внутренней базы не приближает этот результат и добавляет обязательства, которые команда пока не умеет поддерживать.
Запишите сценарий языком партнёра: кто инициирует действие, от чьей организации оно выполняется и где появляется результат. Укажите ограничения первой версии. Если редактирование заявки пока не предусмотрено, это должно быть прямо сказано, а не выясняться из сообщения об ошибке. Публичность интерфейса не означает анонимный доступ или право любого подключившегося читать всех клиентов.
Пройдите маршрут партнёра до выдачи доступа
Ниже — собственная карта запуска для примера с заявкой. Она связывает технический ответ с рабочим результатом и человеком, который может решить проблему. Конкретный способ выдачи доступа выбирают отдельно под продукт и полномочия интеграции.
| Шаг партнёра | Что предоставляет сервис | Что партнёр должен знать | Проверяемый итог | Кто разбирает сбой |
|---|---|---|---|---|
| Запросить подключение | Условия и процедуру подтверждения организации | Кто вправе действовать от её имени | Связь партнёра с разрешённой организацией подтверждена | Ответственный за подключение |
| Получить доступ к испытаниям | Документацию и согласованную тестовую среду | Как получить, хранить и отозвать разрешение | Пример работает с учебными данными | Команда интеграции |
| Передать заявку | Внешний формат и объяснимые ответы | Обязательные поля и значение принятия | Результат связан с конкретным запросом | Владелец операции API |
| Узнать состояние | Способ проверить ранее созданный объект | Идентификатор и область видимости | Партнёр видит только разрешённый результат | Поддержка продукта |
| Повторить после неопределённого ответа | Описанное поведение повторов | Как отличить повтор от новой заявки | Не возникает необъяснимый второй заказ | Разработчик интеграции с владельцем API |
| Сообщить о проблеме | Канал поддержки и безопасный состав диагностики | Как описать запрос без секретов и лишних данных | Обращение можно связать с событием сервиса | Назначенный дежурный или команда |
Внешний контракт не равен структуре внутренней базы
Решите, какие поля имеют смысл для клиента и кто отвечает за их значение. Внутренний служебный статус может меняться вместе с реализацией; не стоит автоматически делать его публичным обязательством. Опишите доступные состояния заявки с точки зрения внешнего процесса: что уже произошло, какое действие ещё возможно и когда результат окончательный.
Для формального описания подойдёт OpenAPI: спецификация задаёт описание HTTP-интерфейса, включая параметры, тело запроса, возможные ответы и схемы безопасности. Это помогает передать контракт людям и инструментам. Но файл описания сам не реализует проверку прав, не исправляет сервер и не подтверждает соответствие фактического поведения документации.
Подготовьте пример минимального корректного запроса и объясните каждое поле, которое партнёр обязан заполнить. Затем покажите отклонённый вариант и способ исправления. Не подменяйте пример огромным объектом из внутренней системы, где половина полей случайна. Партнёр должен понять, какие значения выбирает он, какие назначает сервис и что нельзя использовать как постоянный идентификатор.
Доступ и лимит должны быть понятны до первого сбоя
Выдавайте разрешение на согласованный набор действий и организацию. Возможность прочитать заявку не должна автоматически давать право изменять её или управлять сотрудниками. Для тестового и рабочего подключения предусмотрите различимые настройки и понятную процедуру отзыва. Поддержке не нужен секретный ключ партнёра, чтобы найти его обращение.
Опишите ограничения нагрузки: к чему относится лимит, как клиент узнаёт о его достижении и когда допускается следующая попытка. Не оставляйте это только в устном разговоре. При массовой операции партнёру нужен способ планировать очередь, а не угадывать безопасную частоту по ошибкам. Числа выбирают и проверяют для конкретного сервиса, универсальной безопасной частоты здесь нет.
Например, руководство GitHub описывает обработку ограничения запросов с учётом заголовков ответа и рекомендует временно прекратить обращения. Это пример документированного поведения отдельного API. Его значения и политика не становятся настройками вашего сервиса: полезен сам принцип заранее объяснённой реакции клиента.
Неопределённый ответ важнее красивого успешного примера
Самый неудобный момент подключения — партнёр отправил заявку, но не понял, принял ли её сервер. Требование «просто повторите» может создать дубль, если первая операция уже выполнена. Выберите и задокументируйте способ связать повтор с исходным намерением, а также способ проверить состояние. Конкретный механизм зависит от операции и не должен обещать невозможную безусловную доставку.
Разведите отказ в доступе, некорректные данные, временную недоступность и ситуацию, когда результат ещё определяется. В ответе должно быть достаточно информации для следующего действия. Текст для человека полезен, но клиентское приложение не должно распознавать класс ошибки по случайной формулировке, которую завтра отредактирует поддержка.
Согласуйте идентификатор обращения или другой безопасный способ сопоставить клиентское событие с серверным. В инструкции поддержки перечислите, что присылать: время, операцию, этот идентификатор и описание ожидаемого результата. Отдельно укажите, что нельзя отправлять секреты и полные наборы персональных данных. Возможность восстановить ход операции нужна ещё до роста числа интеграций.
Репетиция подключения без устных подсказок
- Передайте человеку, не писавшему API, опубликованную инструкцию и учебное задание. Начните с получения тестового доступа через объявленную процедуру.
- Попросите выполнить минимальный сценарий и найти результат. Запишите каждое место, где пришлось задавать вопрос автору сервера.
- Предложите заведомо неполный запрос и действие вне выданных прав. По документации должно быть понятно, почему они отклонены.
- Проверьте неопределённый результат и повтор в тестовой среде. Сопоставьте итог с описанным правилом обработки.
- Разберите ограничение запросов без нагрузки на рабочий сервис: используйте подготовленный ответ или управляемый тестовый сценарий.
- Составьте обращение по инструкции поддержки и найдите связанное событие. После исправлений повторите маршрут без личных пояснений разработчика.
Что объявлять готовым к подключению
На старте достаточно небольшого согласованного набора операций, но у него должен быть владелец. Назначьте порядок изменений, канал уведомлений и процедуру прекращения доступа. Укажите, где партнёр увидит актуальную документацию. Не обещайте поддержку всех внутренних функций, если внешнее обязательство относится только к передаче и чтению заявок.
Выпуск собственного API можно включить в разработку веб-приложения, подключение внешнего участника — в интеграцию через API, а проверку полномочий — в аудит API. Готовность подтверждается воспроизводимым маршрутом партнёра: он получает разрешённый результат, понимает ошибки и знает, куда обратиться без передачи секретов.
Вопросы и ответы
Что такое публичное API у SaaS?
Это объявленный внешний интерфейс, через который другие программы выполняют разрешённые действия. Публичная документация не означает, что операции доступны анонимно или без ограничений.
Что должна содержать спецификация OpenAPI?
Она описывает интерфейс HTTP API: операции, параметры, запросы, ответы и применимые схемы безопасности. Конкретное наполнение нужно сверять с реализованным поведением, а бизнес-правила и рабочие примеры объяснять отдельно.
Что объяснить партнёру при ошибке API rate limit exceeded?
Укажите, какой лимит достигнут и по какому правилу можно продолжить запросы. Клиент должен временно остановить обращения и действовать по документации вашего сервиса, а не бесконечно повторять один запрос.