Ресурсы · 33
Развивайте контракты API, не теряя клиентов.
Описывайте запросы, ответы и ошибки; тестируйте версии и делайте веб-хуки безопасными для повторного воспроизведения.
Обновлено · 2 min
Чего помогает достичь это руководство
- Составление контракта
- Уточнение ошибок
- Проверка совместимости
- Планирование вывода из эксплуатации
Быстрая проверка
- Какие клиенты используют каждую операцию?
- Имеют ли ошибки стабильные типы и согласованные статусы?
- Может ли старый клиент перенести изменения?
- Могут ли повторные попытки дублировать действие?
- Как будет объявлен и проверен вывод из эксплуатации?
Пошаговый метод
- 1
Потребители инвентаризации
Перечислите операции, клиентов, использование, версии и владельцев. Отделите наблюдаемое использование от предположений, прежде чем изменять поле.
Результат: карта зависимостей контракта.
- 2
Описание запросов и ответов
Поддерживать описание OpenAPI со схемами, реалистичными примерами, ответами об успехе и неудаче. Проверять его на работающем сервисе.
Результат: версионированный контракт и тесты на соответствие.
- 3
Стабилизация ошибок
Использовать HTTP-статусы в соответствии с их семантикой и, где это полезно, с документированным типом проблемы согласно RFC 9457. Не раскрывать секреты в деталях.
Результат: протестированный каталог ошибок.
- 4
Классифицировать изменения
Проверить обязательные поля, типы, значения, поведение, тайм-ауты и пагинацию. Протестировать старые клиенты на новой версии с репрезентативными примерами.
Результат: матрица совместимости и решение о версии.
- 5
Сделать уведомления надежными
Для веб-хуков планировать аутентификацию, неупорядоченную доставку, дубликаты и повторные попытки. Сделать обработку идемпотентной там, где возможно повторение.
Результат: сценарий воспроизведения и подтверждения.
- 6
Выпуск с возможностью завершения.
Публикация примечаний по миграции, периода сосуществования и контактной информации. Измерение использования старой версии и вывод из эксплуатации только после проверки затронутых пользователей.
Результат: план миграции и подтверждение вывода из эксплуатации.
Показатели управления
| Показатель | Что он измеряет | Первое действие |
|---|---|---|
| Контракт | Описание операций и соответствие поведению сервиса | Исправление расхождений |
| Совместимость | Тестирование репрезентативных клиентов перед внесением изменений | Добавление недостающих случаев |
| Ошибки | Документированные типы без конфиденциальных данных | Пересмотр сообщений и схем |
| Миграция | Использование старой версии с владельцем | Помощь оставшимся клиентам |
Распространенные ошибки
- Предположение о том, что только номер версии сохраняет совместимость
- Документирование только 200 ответов
- Возврат внутренней трассировки или секрета в ошибке
- Предположение, что веб-хуки приходят один раз и в порядке
Часто задаваемые вопросы
Заменяет ли OpenAPI тестирование?
Нет. Сравните описание с реальными ответами и потребностями потребителей.
Требуется ли новая версия для каждого изменения?
Нет. Принимайте решения, исходя из влияния на клиента и поведения по контракту; для несовместимых изменений необходим четкий план.
Почему опечатки?
Они предоставляют клиентам надежный способ выявления проблем и выбора действий.
Официальные ссылки
Ссылки подтверждают метод. Адаптируйте проверки к вашему контексту; они не являются сертификацией. Оригинальные названия ссылок и исходные документы могут быть на другом языке.
