«Причеши» — а причёсывать нечего
Марине дали ссылку на спецификацию, сгенерированную из кода, и сказали: «причеши». В спецификации сорок эндпоинтов, у каждого имена полей и типы. В тот же день поддержка принесла десять тикетов с одинаковой формулировкой: «непонятно, что вернёт ошибка 400».
Причёсывать в этой спецификации нечего. Генератор дал ровно то, что умеет достать из кода: имена и типы. Он не дал смысла поля, единиц измерения, того, что произойдёт при пустом значении, какие поля меняются вместе и что делать после ошибки. Ни одна из этих вещей в коде не записана — она живёт в голове разработчика, и достать её оттуда должна Марина.
Справка API — это reference: описание того, что система делает, а не рассказ о том, как начать. Туториал внутрь неё не вкладывается, и этой одной фразой мы модель типов документации закрываем — она разобрана отдельно. Здесь речь про содержание: из чего состоит единица справки, какие коды ошибок и заголовки в ней обязаны быть описаны и что писатель обязан спросить у разработчика, прежде чем сядет писать.
Плохо спроектированный интерфейс справкой не чинится. Максимум, что даёт хорошая справка, — предсказуемость: интегратор заранее знает, где будет больно, и закладывает это в план. Обещать, что документация сделает API удобным, нельзя — это обещание за чужую работу.
Двенадцать тем идут от того, чем справка является, к тому, как она стареет. По дороге — две стратегии, которыми её читают, три самых тяжёлых провала по данным исследований, развилка кодов ошибок, машиночитаемое тело ошибки, черновики про лимиты и повторы, двухфазный вывод эндпоинта из оборота и OpenAPI глазами писателя, а не инструмента.
Справка — это контракт, а не рассказ
Справка API описывает контракт: что принимает эндпоинт, что возвращает, чем отвечает на неверный вход и как ведёт себя на границах. Это жанр описания, а не повествования. Пошаговый сценарий подключения — отдельный материал; внутрь описания эндпоинта он не вкладывается, потому что читателю справки нужен ответ на точечный вопрос, а не путь от начала.
- Предсказуемость: интегратор заранее знает, где будет больно
- Полноту описания входа и выхода каждого эндпоинта
- Единое место, где описаны общие правила — коды, лимиты, версии
- Проверяемость: по справке можно собрать запрос и сверить ответ
- Что API станет удобным — проектирование справкой не чинится
- Юридической силы: документация не заменяет договор и SLA
- Что интегратор пройдёт путь с нуля — это работа туториала
- Что генератор из кода закроет её содержание
Про юридическую силу стоит сказать отдельно, потому что фраза «согласно вашей документации нам должны» приходит в поддержку регулярно. Она не работает, если в договоре написано иное. В российском финансовом контуре обязательства задаются стандартами и договором, а страница справки — это описание поведения системы, а не источник обязательства.
Дальше нужен аккаунт
Прогресс и монеты сохранятся.