Введение: цель и рамки курса

Аннотация. Курс посвящён проектированию и реализации REST/HTTP API — одному из ключевых навыков современного backend- и fullstack-разработчика. Материал охватывает полный цикл: от выбора ресурсной модели и методов HTTP до документирования контракта, пагинации, обработки ошибок и тестирования. Рассматриваются как фреймворковые подходы (Spring Boot, FastAPI, Flask), так и реализация HTTP-сервера на чистом Java SE без внешних зависимостей.

Цель. Сформировать практические навыки проектирования и реализации RESTful-сервисов, соответствующих принципам архитектурного стиля REST и стандартам HTTP.

Результаты обучения. По завершении курса слушатель сможет: выделять ресурсы предметной области и проектировать URL-структуру; сопоставлять CRUD-операции с HTTP-методами; выбирать стратегию пагинации с учётом профиля нагрузки; проектировать формат ошибок на основе HTTP-кодов состояния; документировать API с помощью OpenAPI; применять инструменты тестирования (Postman, curl) для верификации контракта.

Целевая аудитория. Backend-разработчики, fullstack-инженеры, технические лидеры и архитекторы, имеющие базовый опыт создания HTTP-сервисов и желающие систематизировать знания о проектировании REST API.

Ресурсная модель и именование

Ключевая идея REST — представление предметной области в виде совокупности ресурсов. Ресурс — это любая сущность, к которой можно обратиться по уникальному идентификатору: пользователь, заказ, товар, документ. Идентификатор ресурса выражается через URL.

Проектирование начинается с выбора существительных для обозначения ресурсов и построения логичной иерархии. Для ресурса «книги» корневой URL — /books, для конкретного экземпляра — /books/{id}. Вложенные ресурсы отражают отношение принадлежности: /authors/{id}/books — книги конкретного автора.

Соглашения об именовании должны применяться последовательно во всём API. Ресурсы в URL — существительные во множественном числе: /users, /orders, /items. Глаголы в URL не используются — действие определяется HTTP-методом. Регистр — нижний, разделитель слов — дефис (/user-profiles) или camelCase, но единообразно для всего проекта.

Хорошая практика — сразу предусмотреть версионирование: /api/v1/users. Это защищает клиентов от ломающих изменений при развитии API. Версия может передаваться и через заголовок (Accept: application/vnd.api.v1+json), но путь — наиболее явный и распространённый вариант.

Какой URL соответствует ресурсу «конкретный заказ с идентификатором 42» в RESTful-дизайне?

GET /orders/42

В REST ресурсы обозначаются существительными во множественном числе, а конкретный экземпляр идентифицируется через параметр пути. Метод GET указывает на операцию чтения, а не на действие в URL.

GET /getOrder?id=42

POST /orders/42/get

GET /order/42

Почему в RESTful API не рекомендуется использовать глаголы в URL, например /getUsers или /createOrder?

Действие определяется HTTP-методом, а URL должен идентифицировать ресурс, а не операцию над ним

REST отделяет идентификацию ресурса (URL) от семантики операции (HTTP-метод). Это обеспечивает единообразие интерфейса и позволяет клиентам работать с API предсказуемо.

Глаголы в URL увеличивают длину строки запроса и замедляют маршрутизацию

HTTP-серверы не поддерживают глаголы в URL

Глаголы в URL делают API несовместимым с JSON

HTTP-методы и семантика операций

Какой HTTP-метод следует использовать для создания нового ресурса в коллекции?

POST

POST семантически означает отправку данных для создания подчинённого ресурса в коллекции. Успешный ответ — 201 Created.

GET

PUT

DELETE

Какое свойство HTTP-метода гарантирует, что повторная отправка запроса не изменит состояние сервера иначе, чем однократная?

Идемпотентность

Идемпотентность — свойство, при котором повторный вызов метода с теми же параметрами приводит к тому же результату, что и первый вызов. GET, PUT и DELETE идемпотентны; POST — нет.

Асинхронность

Безопасность

Кэшируемость

Какой код состояния HTTP следует вернуть при успешном создании ресурса?

201 Created

Код 201 Created явно указывает клиенту, что запрос привёл к созданию нового ресурса. В заголовке Location обычно передаётся URL созданного ресурса.

200 OK

204 No Content

302 Found

Формат данных и схемы

Современные REST API используют JSON как основной формат обмена данными благодаря лаконичности и нативной поддержке в браузерах и большинстве языков программирования. Альтернатива — XML — сохраняется в legacy-системах и некоторых корпоративных протоколах.

При проектировании API определяется схема данных для каждого ресурса: перечень полей, их типы, обязательность и правила валидации. Например, для ресурса «книга»: id (integer, генерируется сервером), title (string, обязательное, 1–200 символов), authors (массив строк), isbn (string, уникальное), publication_year (integer, 4 цифры), available (boolean, по умолчанию true).

Схему рекомендуется документировать формально — с помощью JSON Schema или в составе спецификации OpenAPI. Это обеспечивает единое понимание формата всеми участниками: backend-разработчиками, frontend-командой, тестировщиками и внешними потребителями API.

Обязательные и опциональные поля разделяются явно. Для опциональных полей задаются значения по умолчанию. Правила валидации (минимальные и максимальные длины, диапазоны числовых значений, форматы строк) должны быть согласованы и проверяться как на клиенте, так и на сервере.

Какой формат данных наиболее распространён в современных REST API для обмена информацией?

JSON

JSON обеспечивает компактное представление структурированных данных и поддерживается нативно в JavaScript, Python, Java, Go и большинстве других языков. Это делает его де-факто стандартом для REST API.

XML

YAML

CSV

Какая спецификация позволяет формально описать структуру API: endpoints, схемы запросов и ответов, коды состояния?

OpenAPI

OpenAPI (ранее Swagger) — стандарт описания REST API, позволяющий документировать контракт в машиночитаемом формате. На основе спецификации генерируются интерактивная документация, клиентские SDK и тесты.

JSON Schema

GraphQL SDL

WSDL