Опорная идея
API-документ должен быть проверяемым: endpoint, method, auth, headers, request body, response body, error codes, rate limits and examples. Пример должен быть рабочим и соответствовать текущей версии. Если документация расходится с API, доверие ломается быстрее, чем от отсутствия документации.
Хороший API reference отделяет обязательные поля от опциональных и объясняет ошибки человеческим языком.