Правила документации

Эти правила применяются к Reseller API v1. Документация описывает реализованный контракт, а не желаемое поведение. Основа проверки: маршруты, middleware, валидаторы, ресурсы ответов, сервисы операций и тесты текущего релиза. Поведение конкретного реестра и настройки оператора указываются отдельно.

Использованные рекомендации

Источник	Что применяем
Diátaxis	Разделяем учебный сценарий, практические инструкции, справочник и объяснение модели.
Google AIP-192	Описываем каждый метод и поле, допустимые значения, единицы, значения по умолчанию, побочные эффекты и ошибки.
Google API reference guidance	Указываем назначение, параметры, результат, исключения и рабочие примеры.
OpenAPI 3.1	Один структурированный контракт для схем, примеров, страниц методов и машинных клиентов.
RFC 9110	Не смешиваем HTTP-успех с завершением бизнес-операции.
RFC 6585	Описываем HTTP 429 и фактическое использование Retry-After.
llms.txt	Предоставляем индекс и Markdown для обработки ИИ. Это предложение формата, не официальный стандарт совместимости ИИ.

Принципы AIP-192 адаптированы к русскоязычному REST API. Это не заявление о сертификации Google или полном соответствии protobuf-правилам. Формат ошибок платформы собственный; он не объявляется RFC 9457 Problem Details.

Обязательный состав метода

• HTTP-метод и путь, назначение, доступные окружения и необходимые scopes.
• Параметры пути, query, headers и тела: тип, обязательность, nullable, длина, диапазон, enum, значение по умолчанию и условные зависимости.
• Успешные ответы с полным примером и расшифровкой вложенных полей.
• Применимые статусы ошибок, стабильный код, условие возникновения и действие клиента.
• Требования к Idempotency-Key, повтору, асинхронному завершению и финансовым последствиям.
• Ограничения регистратора и условия, зависящие от настроек, без обещания недоступных возможностей.

«Все ответы» означает все документируемые ветки HTTP/бизнес-контракта и типы результатов операций. Тексты сообщений, произвольные сообщения внешнего реестра и ошибки reverse proxy не являются конечным перечислимым набором. Клиент обязан иметь обработчик неизвестного кода, статуса и не-JSON ответа.

Проверки изменений

Спецификация собирается из тематических YAML-фрагментов. Страницы методов не редактируются независимо от неё. Изменение запроса или ответа должно сопровождаться изменением схемы, примера, сценария и теста.

Перед публикацией проверяются разбор OpenAPI и ссылки $ref, соответствие маршрутам, соответствие примеров схемам, ссылки руководств, машинные загрузки, сборка и отображение портала. Исполняемые примеры тестируются на подставном транспорте без операций в реестре.

Статические проверки не заменяют проверку интеграции в sandbox. Не считаем наличие примера доказательством принятия произвольного контакта NIC.KZ или доступности домена. Дату релиза API и окружение необходимо согласовывать с оператором независимо от даты публикации портала.

Совместимость

Клиенты должны игнорировать неизвестные дополнительные поля, не разбирать человекочитаемое message как машинный код, не считать новый статус успешным по умолчанию и сохранять исходные идентификаторы для диагностики. Удаление или изменение смысла поля требует оценки совместимости и уведомления интеграторов; префикс /v1 сам по себе не является обещанием неизменности всех внешних реестров.

Из документации исключаются реальные токены, персональные данные клиентов, секреты ЭЦП и production-конфигурация. Операторские инструкции по деплою не входят в сценарий подключения реселлера.