API
REST-моделирование: спроектируй API заказов, переживающий изменения
Читать про моделирование ресурсов — не то же, что отстоять контракт через реальную смену схемы. Спроектируй и построй небольшой API заказов, затем докажи, что он переживает три вещи, ломающие наивные API в production: переименование колонки, неохраняемый переход состояния и ретраенное создание.
Преврати ментальную модель юнита в рабочий API: моделируй существительные вместо глаголов, выражай не-CRUD действия как охраняемые переходы, разъедини representation и схему mapping-слоем и сделай создание retry-safe — доказывая каждое свойство, а не утверждая его.
Спроектируй и построй небольшой REST API управления заказами (Orders, Items, Refunds), чей контракт переживает переименование колонки БД, отказывает в нелегальном переходе состояния и возвращает исходный результат на ретраенном создании — демонстрируя каждое свойство транскриптом запрос/ответ.
- Транскрипт, доказывающий разъединение со схемой: переименуй колонку БД (например, full_name в display_name) БЕЗ изменения wire-representation, показав идентичные запрос/ответ до и после миграции.
- Транскрипт, доказывающий охраняемый переход: POST /orders/{id}/cancel успешен на отменяемом заказе и отклонён с 4xx на уже отгруженном, а прямая попытка записать status через PATCH отвергнута.
- Транскрипт, доказывающий retry-safety: один и тот же POST, отправленный дважды с одним Idempotency-Key, создаёт ровно один resource и возвращает тот же id/результат оба раза.
- Одностраничная карта URL и короткий разбор: для каждого не-CRUD действия — выбрал ли ты action-подресурс или transition-ресурс и почему.
- Добавь курсорную пагинацию, фильтрацию и сортировку на коллекции (GET /orders?status=open&sort=-created_at&cursor=...) и задокументируй, почему это query-параметры, а не новые эндпоинты.
- Добавь HATEOAS-ссылки (_links с легальными следующими действиями на состояние заказа) и напиши клиент, который следует ссылке cancel вместо хардкода URL — затем отметь, что это стоило против level-2 REST.
- Добавь версионирование API и продемонстрируй эволюцию representation без поломки v1-клиентов, поглотив изменение в mapping-слое.
- Добавь OpenAPI-спецификацию, сгенерированную из реализации, и contract-тест, который роняет сборку, если ответ сливает поле, не указанное в документированном representation.
Это цикл проектирования, который ты запускаешь на каждом реальном API: моделируй существительные и пусть метод несёт глагол; выражай не-CRUD переходы как охраняемые action- или transition-ресурсы, чтобы сервер владел стейт-машиной; держи вложенность мелкой и расширяй вместо обхода; сериализуй через mapping-слой, чтобы representation был контрактом, которым ты владеешь, а БД оставалась рефакторимой; и делай создание retry-safe через idempotency key. Сделав это раз на небольшом API заказов, ты превращаешь правила, которые можно процитировать, в формы, к которым тянешься рефлекторно.