REST API¶

REST (Representational State Transfer) - архитектурный стиль клиент-серверного взаимодействия: правила, по которым приложения обмениваются данными. REST API - API, построенное по этим правилам.

Stateless - сервер не хранит состояние клиента, каждый запрос несёт всю нужную информацию
Ресурсы - все данные представлены ресурсами с адресами: /users, /products
Стандартные методы HTTP - GET, POST, PUT, PATCH, DELETE
Кэшируемость - ответы сервера можно кэшировать
Слоистая система - клиент не знает, говорит он с сервером напрямую или через прокси
Формат - на практике JSON

Note

В исходной версии было «формат json (xml устаревшее)». REST к формату не привязан: представление ресурса может быть JSON, XML, HTML - что угодно по Content-Type. JSON просто стал стандартом де-факто.

См. REST в Spring MVC и SOAP и REST.

Имена ресурсов¶

Существительные, а не глаголы. Действие задаёт HTTP-метод, а не адрес.
```
Плохо:   /getUsers, /createOrder, /deleteProduct
Хорошо:  GET /users, POST /orders, DELETE /products/{id}
```
Множественное число - единообразие и явное указание на коллекцию.
```
GET /users     - все пользователи
GET /users/1   - конкретный пользователь
```

Нижний регистр и дефисы (kebab-case).

Плохо:   /UserOrders, /productCategories
Хорошо:  /user-orders, /product-categories

Без пробелов и спецсимволов. Вместо пробела - дефис: /product-categories лучше, чем /product%20categories.

Иерархия и параметры¶

Вложенность для связанных сущностей. Если ресурс принадлежит другому, это видно по адресу:
```
/users/{userId}/orders             - заказы пользователя
/users/{userId}/orders/{orderId}   - конкретный заказ
```
Глубина вложенности - не больше 2-3 уровней. Глубже - фильтрация через параметры:
```
Плохо:   /users/1/orders/5/products/3/reviews
Лучше:   /reviews?productId=3&userId=1
```

Фильтрация, сортировка, пагинация - query-параметрами:

GET /users?role=admin&status=active
GET /products?sort=-price,created_at    - минус = по убыванию
GET /articles?page=2&limit=10

Версионирование¶

Самый простой способ - версия в пути:

/api/v1/users
/api/v2/users

Другие способы (заголовок, параметр, media type) и как Spring Framework 7 поддерживает их из коробки - в Версионирование API.

Документирование¶

Swagger (OpenAPI) - описание API и интерактивная документация.

TODO¶

HTTP-методы: безопасность и идемпотентность каждого (см. HTTP)
HATEOAS и модель зрелости Ричардсона
контракт через OpenAPI: contract-first и code-first
тестирование REST API