# Технический писатель: первый запуск API

Авторское учебное условие; локальная фикстура не является HTTP-сервером.

## Практикум: исправить первый запуск API

Это авторская задача. Старый quickstart предлагает POST /v0/tasks с application/x-www-form-urlencoded, полем task, без bearer-заголовка и ожидаемым ответом 200. Дано подтверждение владельца: актуальная учебная версия — v1, ниже перечислен её согласованный контракт. Нужно подготовить законченные quickstart, справку и структурное описание, а также проверить пример.

Создание выполняется через POST /v1/tasks. Требуются Authorization: Bearer training-token и точный Content-Type: application/json. Тело — JSON-объект только с text. Text — строка длиной от 1 до 80 Unicode code points; после trim она не должна быть пустой. Сохраняется исходный текст без обрезки пробелов. Успех возвращает 201 и объект с положительным целочисленным id и text.

Чтение GET /v1/tasks/{id} требует того же bearer-заголовка, возвращает 200 и созданный объект. Id в пути записывается положительными десятичными цифрами без ведущих нулей. Нет задачи — 404. Нет правильного токена — 401 до проверки маршрута; неверный тип тела POST — 415; неверная структура — 400. Неподдержанный метод на известном маршруте — 405.

Training-token — публичное значение учебной фикстуры, не действующий секрет. Хранилище находится в памяти одного экземпляра dispatch. Отдельный запуск начинает с пустого состояния, поэтому создание и чтение объединены в client.mjs. Сетевого адреса и удалённого аккаунта нет. Успешный повтор POST создаёт новую задачу: идемпотентность не обещается.

## Готовый quickstart и его результат

В готовой инструкции перед командой указано: нужен Node.js с ES modules, файлы client.mjs и fixture.mjs должны лежать рядом, зависимости устанавливать не требуется. Затем читатель переходит в распакованный каталог и запускает `node client.mjs`. Клиент уже содержит правильные заголовки и JSON с text «Сверить отчёт».

Первый ответ: POST /v1/tasks, status=201, body={"id":1,"text":"Сверить отчёт"}. Второй: GET /v1/tasks/1, status=200 с тем же телом. Обоим соответствует content-type: application/json. Команда действительно выполнена на Node.js 26.8.2; ответ не выдуман для иллюстрации. Полные объекты сохранены в execution-log.json.

Готовый quickstart также объясняет 401, 415 и 400, а не заканчивается единственным «успех». Справка reference.md описывает границы text, форму ошибки {"error":"код"}, повторное создание и сброс памяти после запуска. openapi.json связывает request/response схемы и bearer requirement. Имена файлов в этих ссылках существуют в архиве; будущие материалы читателю не обещаются.

Реплика владельцу продукта после проверки: «Обновил путь на v1, добавил учебный bearer, JSON-поле text и ожидаемый 201. Создание и чтение проверены в локальной фикстуре; справка и схема согласованы с этим примером. Сетевой сервис не проверялся: его в условии нет. Для публикации документации реального API нужно отдельно подтвердить адрес среды и выполнить интеграционный прогон». Это описание результата, а не обращение к пользователю API.

## Проверки и ошибки решения

Автоматическая проверка вызывает dispatch и сравнивает успешные статусы и полные тела POST/GET с expected.json. Для 400, 401, 404, 405 и 415 дополнительно сверяются полные тела {error:код} и тип JSON-ответа. Отдельно проверяются 401 без токена, 415 при text/plain, 400 для NULL, массива, отсутствующего text, пустой/пробельной строки, неверного типа и лишнего поля. 80 emoji принимаются, 81 отклоняется: это проверяет Unicode code points, а не длину JavaScript-строки в UTF-16 units.

Проверяются чтение, регистронезависимость имён заголовков, отсутствие записи, путь с ведущим нулём и неподдержанный метод. Ошибочные запросы не расходуют id: первая созданная задача получает 1. Изменение полученного объекта не должно менять хранимый текст; ответ возвращает копию. Эти проверки защищают конкретное поведение фикстуры, не безопасность реального многопользовательского API.

Негативный режим воспроизводит старый запрос без авторизации и получает 401 вместо требуемого успешного создания. Проверка завершается кодом 2. Он не доказывает по отдельности каждую ошибку старой инструкции, поэтому штатные тесты дополнительно проверяют тип тела и другие ветви. Ошибка ожидания «201 вместо старого 200» также сверяется с реально выполненным успешным запросом.

Плохое решение — исправить только стиль, оставить v0 и сказать «ответ будет успешным». Другая ошибка — показать curl к несуществующему серверу либо назвать внутреннюю фикстуру проверкой настоящей интеграции. Здесь ограничение явно включено в quickstart, справку, README и вывод теста.

## Файлы для репетиции

Скачай [полный практикум техписателя](practice.zip), открой [условие и решение с копированием](copy.html) или [Markdown](practice.md). В архиве находятся quickstart.md, reference.md, openapi.json, expected.json, три исполняемых файла .mjs, README и execution-log.json.

Выполни `node client.mjs`, затем `node check.mjs`. Для намеренно неверного примера — `node check.mjs --negative`, ожидаемый код 2. Фактический прогон сделан на Node.js 26.8.2. Проверены исполнение локальных примеров и ключевые поля схемы; HTTP-сокет, внешняя среда, полный OpenAPI-валидатор и пользовательское исследование не запускались.

На репетиции сначала сформулируй читателя и первый результат, затем покажи, откуда взяты изменения и как они проверены. После этого предложи следующий шаг для реального продукта: согласовать адрес и права тестовой среды, проверить интеграцию и включить обновление документации в релизный процесс.
