REST архитектура (II)

Одним из свойств REST-архитектуры является манипулирование объектами средствами ограниченного числа операций. В рамках HTTP это GET, POST, DELETE, PUT.

До этого мой API был построен в стиле:

GProjectEstimates getProjectEstimates(String projectName);

GProjectEstimates fixInitialEstimate(String projectName);

GActiveProject createProject(String name);

void deleteProjects(Set projectNames);

Т.е. определен некоторый интерфейс в терминах действий, предоставляющий доступ к методам по работе с данными. Для REST я переформулировал его в терминах объектов-ресурсов:

/{user}/time - Ресурс «Затраты времени пользователя»

/{user}/projects - Ресурс «Проекты пользователя»

/project/{projectNumber} - Ресурс «Проект»

/project/{projectNumber}/initial - Ресурс «Начальное планирование проекта»

/project/{projectNumber}/current - Ресурс «Текущее состояние проекта»

Для каждого из ресурсов задан URI. Важным моментом является то, что представление одного и того же ресурса (т.е. ресурса имеющего один и тот же URI) для разных пользователей не должны различаться. Если представления различны, то по сути это разные ресурсы и должны иметь различные URI. Поэтому ресурс «Затраты времени пользователя» включает в свой URI имя пользователя {user}.

Над каждым ресурсов определены действия:

Ресурс «Проекты пользователя»
/{user}/projects

GET - Возвращает коллекцию ссылок на проекты с названиям вида.
PUT - ничего
DELETE - ничего
POST - Создает новый проект, добавляет в коллекцию и возвращает его URI в Location. Может быть указано имя проекта, иначе создается самостоятельно.

GET, очевидно, получает представление ресурса с сервера.
PUT помещает на сервер по указанному URI новый ресурс или заменяет имеющийся.
DELETE удаляет ресурс.
POST позволяет выполнять модификации или создание нового ресурса. Естественно действие может быть различным в зависимости от переданного в POST содержимого.

GET может возвращать несколько разное содержимое в зависимости от запрошенного клиентом типа результата.

Оба метода PUT и POST могут использоваться для создания ресурсов, но есть различие. Для использования PUT необходимо знать URI вновь создаваемого объекта, в то время как POST может сам создать объект и вернуть URI созданного объекта клиенту. Такая схема использована выше, когда выполнение POST на ресурсе "проекты пользователя" приводит к созданию нового проекта и возврату URI вновь созданного объекта.

Интересно, что наличие метода PUT само собой подвигает к программированию в стиле - загрузка объекта и передача на клиента - изменение Detached-объекта на клиентской стороне - возврат его на сервер для сохранения изменений, в противоположность специальным API часто характерным для RPC.