Лекция «Документация API — из чего состоит справка, по которой интеграция получается с первого раза»

Около 50 минут на 12 тем. Прогресс сохраняется, поэтому лекцию можно проходить частями и возвращаться к ней позже.

Начало — да: первые 1 тема открыты сразу, без регистрации. После бесплатной регистрации откроются темы до 2-й — вместе с частью из 36 тестов и монетами за верные ответы. Полная лекция — 99 ₽ навсегда, либо подписка на все лекции платформы от 499 ₽ в месяц.

Двенадцать тем о том, что должно оказаться внутри справки API. Начало — с границы жанра: справка описывает контракт, обещает предсказуемость, а не удобство, и договор с SLA не заменяет. Дальше — два читателя одной страницы: по данным Meng, Steinhardt и Schubert (2018) разработчики после общего знакомства с API расходятся на стратегии «от концепций» и «от кода», поэтому справка только из примеров и справка только из объяснений провальны одинаково. Разбор идёт по единице справки — documentation unit из работы Uddin и Robillard, где на 323 опрошенных разработчика и 179 единиц документации тремя самыми тяжёлыми проблемами названы неоднозначность, неполнота и неверность, а шесть проблем из десяти признаны блокирующими, то есть останавливающими работу. Восемь обязательных частей описания эндпоинта показывают, где заканчивается генератор: имя и тип он даёт, единицы измерения, поведение при пустом значении и связанные поля — нет. Отдельно разобраны правило про пример, видимый без прокрутки (и почему переносить надо правило, а не трёхколоночную вёрстку), развилка клиентских кодов по RFC 9110 со сменой имени 422 на Unprocessable Content, машиночитаемое тело ошибки по RFC 9457 с разделением постоянного title и переменного detail, а также черновики IETF про RateLimit и Idempotency-Key, которые нельзя называть стандартами. Завершают лекцию двухфазный вывод из оборота через Deprecation (RFC 9745) и Sunset (RFC 8594) с двумя разными форматами даты, разбор случая X (Twitter) 2023 года с недельным сроком предупреждения и четыре обязательных элемента примечания об отключении, версии OpenAPI глазами писателя и разделение «прикладной стандарт / спецификация» в стандартах Банка России. Финал — чек-лист из десяти вопросов к разработчику.

Нет, и это осознанная граница. Разбираются принципы, которые переживают смену инструмента: состав описания эндпоинта, семантика кодов ответа, формат тела ошибки, механика вывода из оборота. OpenAPI присутствует не как софт, а как формат-стандарт — язык, на котором справка описана машиночитаемо, и его структуру писатель обязан понимать, даже если сам спецификацию не редактирует. По той же причине из разбора трёхколоночной справки вынесено правило («у каждого раздела есть пример, видимый без прокрутки»), а не раскладка: колонки задаёт платформа, а писатель отвечает за наличие примера.

Нет, потому что правильного ответа здесь не существует. HTTP не предписывает, что возвращать на ошибку валидации: одни API отдают 400 на всё, другие держат различие с 422 строго, и обе трактовки допустимы. Писатель документирует то, что делает сервис, а не то, что ему нравится, поэтому назвать чужое решение ошибкой проектирования он не вправе. Что лекция даёт вместо ответа — рабочее правило: выяснить у разработчика, какое различие принято в этом API, и описать его один раз в общем разделе. Ровно это закрывает поток тикетов «непонятно, что вернёт ошибка 400».