Представлять действия (глаголы) в REST URI

У меня есть операция печати для моих документов клиента. Мне нужны и другие стандартные операции, такие как добавление, обновление, удаление. Итак, у меня есть следующее:

• Для создания нового клиента:
  URI = / customer / {id}, тип = POST, Methodname = CreateCustomer ()
• Для обновления:
  URI: / customer / {id}, тип = PUT, метод = UpdateCstomer ()
• Для удаления клиента:
  URI = / customer / {id}, тип = DELETE, имя метода = DeleteCustomer ()
• Для просмотра:
  URI: / customer / {id}, type = GET, method = GetCustomer ()

Теперь, если мне нужно распечатать документ для этого клиента, мне нужна функция печати. Мой URI может выглядеть так: / customer / {id}, type = POST, method = PrintCustomer (). Но я использовал этот тип URI и POST для CreateCustomer. Я хотел, чтобы URI выглядел так: / customer / Print / {id}, type = POST, method = PrintCustomer ().

Но у меня не может быть глагола "Print" в моем URI. Какой лучший способ сделать это? Я думал о / customer / document / {id} как URI ... но я столкнусь с той же проблемой. У меня были бы операции CRUD над «документом». Итак, я снова исчерпал то, что использовал бы для «печати». Пожалуйста, порекомендуйте.

POSTне означает «создать», это означает «процесс». Вы можете создать новый ресурс, разместив подходящий запрос на существующем ресурсе (т. Е. Отправить, /customersчтобы создать нового клиента). Но вы также можете использовать POSTдля выполнения всех других действий, которые не соответствуют изящной парадигме CRUD.

В случае печати вы должны рассматривать сам процесс печати как ресурс. Вы просите систему создать «задание на печать» для вас. Это означает, что у вас может быть prints/ресурс, который действует как контейнер для всех запрошенных отпечатков. Когда вы хотите распечатать что-то, вы POSTотправляете документ на этот ресурс, который содержит всю информацию о распечатке, которую вы хотите создать, идентифицируя ресурсы, которые вы хотите распечатать, со ссылками на них.

Как документ JSON, он может выглядеть так:

{
   contents: ["http://site/customers/12345"],
   paper-size: "A4",
   duplex: "true"
}

Очевидно, вам нужно настроить это, чтобы иметь отношение к тому, что вы хотите сделать. Главное, чтобы вы идентифицировали другие ресурсы для печати, указав их URL.

В ответ на запрос вы можете просто вернуть a 200 OKили a 204 No-Contentи рассматривать их как процесс «забей и забудь». Однако, если вы хотите улучшить его, вы можете вернуться 201 Createdи указать URL вновь созданного задания на печать, например /prints/12345.

Затем пользователь может выполнить операцию GETнад ресурсом, чтобы увидеть состояние своего задания на печать (ожидает выполнения, выполняется и т. Д.), Или может запросить отмену задания, выполнив команду DELETE.

Как только вы перефразируете проблему с точки зрения ресурсов, дизайн RESTful должен появиться естественным образом и дать вам возможность расширяться и совершенствоваться способами, которые вы, возможно, сразу не рассмотрели.

Я сделал это раньше. Чтобы напечатать документ, я просто возвращаю PDF-версию ресурса. Клиенту нужно только отправить GET-запрос на ресурс с помощью заголовка Accept application / pdf.

Это также позволяет избежать создания нового URI для временного ресурса, такого как задание на печать. Использование HTTP-заголовка также является частью REST и поддерживает чистоту URI.

Просто добавьте параметр в GET текущего URI

Довольно типично использовать URI для нескольких действий.

Если вы говорите об одном и том же ресурсе, но о другом действии, вы должны определить его как параметр.

/ Клиент / {идентификатор}? = Печать верно

Затем, где вы определяете свой метод GET, вы обнаруживаете наличие параметра печати и обрабатывает его по-другому.

REST определяется следующим образом:

• POST - Создать запись, актив или ресурс
• PUT - обновление, запись, актив или ресурс
• УДАЛИТЬ - Удалить, запись, актив или ресурс

GET, с другой стороны, предназначен для использования несколькими способами, потому что обычно существует множество различных форм, которые ресурс может быть извлечен. Вот почему GET-запросы представлены в виде строки запроса. Если бы вы работали с ресурсом базы данных, вы бы в буквальном смысле извлекали представление через запрос, но REST преднамеренно абстрагируется до более высокого уровня, поскольку он предназначен для работы со многими различными типами ресурсов.

Спецификация REST довольно дальновидна, хотя API только начинает интенсивно ее использовать.

Если вам интересно узнать больше о протоколах REST, я настоятельно рекомендую вам прочитать " Haters Gonna Hate HATEOAS ".

Обновить:

@Shauna указал на интересную дыру в моих рассуждениях. Там нет истинно правильного пути, и многие формы считаются приемлемыми. Я подумал об этом еще немного, и, поскольку вы планируете использовать для преобразования данных в другое представление, имеет смысл определить преобразование как новый MIME-тип.

Например, вы можете представить URI как:

/customer/{id}+print

Где вы можете установить тип содержимого ответа text / html + print. Таким образом, у вас также будет возможность определить больше преобразований в будущем.

Например:

// for application/json
/customer/{id}+json

// for application/atom+xml
/customer/{id}+atom

В любом случае, все формы являются приемлемыми. Реализация, которую вы решите, больше зависит от личных предпочтений и возможностей вашего сервера.

В сторону: позвольте мне уточнить, так как, кажется, есть некоторая путаница. Параметр запроса «печать» и / или тип содержимого используется для указания того, как преобразуется ресурс. Не как запустить физическое задание на печать. Из соображений безопасности доступ на аппаратном уровне всегда предоставляется пользователю / клиенту / браузеру.