Разные подходы к структуре REST API:

1) Чистый CRUD-стиль

GET /users  
POST /users  
PUT /users/{id}  
DELETE /users/{id}

👍 Просто и предсказуемо
👎 Начинает хромать при действиях вне CRUD

2) Эндпоинты-действия

POST /users/{id}/deactivate  
POST /orders/{id}/cancel

👍 Ясное указание на сайд-эффекты
👎 Нарушает REST-идеи (глаголы в URL)

3) Вложенные ресурсы

GET /users/{id}/orders  
POST /users/{id}/addresses

👍 Удобно моделирует связи между сущностями
👎 Может вырасти в избыточную иерархию, тяжело поддерживать

4) Плоская структура + фильтры

GET /orders?userId=123  
GET /products?category=books&page=2

👍 Гибкие запросы
👎 Требует строгой валидации query-параметров

5) Версионирование API

GET /v1/users  
Accept: application/vnd.myapp.v2+json

👍 Безопасное развитие API
👎 Увеличивает накладные расходы на поддержку

👉 Java Portal