Проектирование RESTful API
Превращаем данные в понятный и предсказуемый набор URL и методов
- моделировать данные как ресурсы и проектировать их URL,
- сопоставлять HTTP-методы с созданием/чтением/обновлением/удалением и знать, какие из них безопасны или идемпотентны,
- возвращать правильные коды состояния при успехе и ошибке,
- объяснить, почему REST не хранит состояние, и проектировать с учётом этого.
1. Ресурсы: моделируем существительные, а не действия
Сердце REST — это ресурс: сущность, о которой знает ваша система, например задача, пользователь или заказ. Ресурс — это существительное. Ошибка новичков в том, что они проектируют вокруг глаголов — /createTask, /getTask, /deleteTask — а значит, каждое новое действие требует нового URL, и клиент вынужден их все запоминать.
В REST всё наоборот. Вы предоставляете один URL на ресурс и позволяете HTTP-методу описывать действие:
- коллекция живёт по пути во множественном числе:
/tasks - отдельный элемент — под ней по идентификатору:
/tasks/42
Аналогия. Представьте картотечный шкаф. /tasks — это ящик с надписью «Задачи»; /tasks/42 — одна папка внутри него. Вы никогда не подпишете ящик «открыть ящик задач» — ящик это существительное, а открыть, добавить или убрать папки — это отдельные действия, которые вы выполняете над ним. HTTP-методы и есть эти действия.