Представляють дії (дієслова) в URI REST

У мене є операція друку для виконання документів для клієнта. Мені потрібні й інші стандартні операції, які можна виконати, як-от додавання, оновлення, видалення. Отже, у мене є наступне:

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

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

Але я не можу мати в своєму 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 header / pdf.

Це також уникає створення нового URI для тимчасових ресурсів, таких як завдання друку. Використання заголовка HTTP також є частиною REST, і він підтримує чистий URI.

Просто додайте параметр до GET поточного URI

Досить типово використовувати URI для декількох дій.

Якщо ви говорите про один і той же ресурс, але про іншу дію, ви визначите його як параметр.

/ customer / {id}? print = true

Тоді, де ви визначаєте свій метод GET, ви виявляєте наявність параметра друку та обробляєте його по-різному.

REST визначається наступним чином:

• POST - Створення запису, об’єкту або ресурсу
• PUT - оновлення, запис, актив або ресурс
• DELETE - Видаліть, записуйте, об’єкт або ресурс

З іншого боку, GET призначений для використання декількома способами, оскільки зазвичай існує багато різних форм, з яких ресурс може бути отриманий. Ось чому запити GET представлені у вигляді рядка запиту. Якщо ви працювали з ресурсом бази даних, ви буквально отримували б представлення даних за допомогою запиту, але REST навмисно абстрагується на більш високий рівень, оскільки він призначений для обробки багатьох різних типів ресурсів.

Специфікація REST є досить перспективною, хоча API лише недавно починають активно її використовувати.

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

Оновлення:

@Shauna вказав на цікаву дірку в моїх міркуваннях. Не існує справжнього правильного шляху, і багато форм вважаються прийнятними. Я дещо подумав над цим, і оскільки ваше призначення призначене для перетворення даних у інше представлення, має сенс визначити перетворення як новий тип MIME.

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

/customer/{id}+print

Де ви могли встановити відповідь Content-Type на текст / html + print. Таким чином, ви також матимете можливість визначити більше перетворень у майбутньому.

Наприклад:

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

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

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

У бік: Дозвольте уточнити, оскільки, здається, існує деяка плутанина. Параметр запиту 'print' та / або тип вмісту використовується для визначення способу перетворення ресурсу. Не як запустити фізичне завдання друку. З міркувань безпеки доступ на апаратному рівні завжди залишається користувачеві / клієнту / браузеру.