REST — это набор соглашений, делающих API предсказуемым. Ключевая идея: всё — ресурсы, у каждого свой адрес, а действия задаёт HTTP-метод.
Хорошие правила именования эндпоинтов: • используйте существительные во множественном числе: /users, /orders, а не /getUsers; • идентификатор в пути: /users/42; • вложенность для связей: /users/42/orders (заказы пользователя 42); • фильтры и сортировку — в query-параметрах: /users?city=Москва&sort=age.
Действие выражают методом, а не словом в адресе:
GET /users — список GET /users/42 — один POST /users — создать PUT /users/42 — изменить DELETE /users/42 — удалить
Так один набор адресов покрывает все операции, и API легко угадывается. Версионируют API через префикс: /v1/users — чтобы менять его, не ломая старых клиентов. Предсказуемость — главная ценность REST: зная правила, разработчик угадывает адреса, почти не заглядывая в документацию.