Rappresenta azioni (verbi) nell'URI REST

Ho un'operazione di stampa da eseguire per i documenti dei miei clienti. Ho bisogno di eseguire anche le altre operazioni standard, come aggiungere, aggiornare, eliminare. quindi, ho il seguente:

• Per creare un nuovo cliente:
  URI = / customer / {id}, digitare = POST, Nome metodo = CreateCustomer ()
• Per l'aggiornamento:
  URI: / customer / {id}, digitare = PUT, method = UpdateCstomer ()
• Per Elimina cliente:
  URI = / cliente / {id}, digitare = ELIMINA, Nome metodo = Elimina cliente ()
• Per Visualizza:
  URI: / customer / {id}, digitare = GET, method = GetCustomer ()

Ora, se devo stampare un documento per quel cliente, ho bisogno di una funzione di stampa. Il mio URI potrebbe essere simile al seguente: / customer / {id}, type = POST, method = PrintCustomer (). Ma ho usato quel tipo di URI e POST per CreateCustomer. Volevo che l'URI fosse simile a questo: / customer / Print / {id}, type = POST, method = PrintCustomer ().

Ma non posso avere il verbo "Stampa" nel mio URI. qual'è il miglior modo per farlo? Ho pensato a / customer / document / {id} come l'URI ... ma incontrerò lo stesso problema. Avrei le operazioni CRUD sul "documento". Quindi, ancora una volta esaurisco ciò che avrei usato per "stampare". Si prega di avvisare.

POSTnon significa "creare", significa "processo". È possibile creare una nuova risorsa inviando una richiesta adatta a una risorsa esistente (ovvero postare /customersper creare un nuovo cliente). Ma puoi anche usare POSTper compilare tutte le altre azioni che non corrispondono a un chiaro paradigma CRUD.

Nel caso della stampa, è necessario considerare l'atto di stampa come una risorsa stessa. Stai chiedendo al sistema di creare un "lavoro di stampa" per te. Questo significa che puoi avere una prints/risorsa che funge da contenitore per tutte le stampe richieste. Quando vuoi stampare qualcosa, sei POSTun documento su questa risorsa che contiene tutte le informazioni sulla stampa che vuoi creare, identificando le risorse che vuoi stampare con collegamenti ad esse.

Come documento JSON, potrebbe assomigliare a questo:

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

Ovviamente, è necessario personalizzarlo per essere pertinenti a ciò che si desidera fare. La cosa fondamentale è che stai identificando altre risorse da stampare specificando il loro URL.

In risposta alla richiesta, potresti semplicemente restituire a 200 OKo a 204 No-Contente trattarlo come un processo di fuoco e dimentica. Tuttavia, se si desidera migliorarlo, è possibile restituire 201 Createde specificare l'URL del processo di stampa appena creato, ad es /prints/12345.

Un utente potrebbe quindi eseguire una ricerca GETsulla risorsa per vedere lo stato del proprio lavoro di stampa (in sospeso, in corso, ecc.) Oppure richiedere che il lavoro venga annullato emettendo un DELETE.

Una volta riformulato il problema in termini di risorse, il design RESTful dovrebbe essere naturale e offrirti l'opportunità di espandersi e migliorare in modi che potresti non aver immediatamente preso in considerazione.

L'ho già fatto prima. Per stampare un documento restituisco solo una versione pdf di una risorsa. Il client deve solo inviare una richiesta GET per la risorsa con accetta intestazione application / pdf.

Ciò evita anche di creare un nuovo URI per risorse temporanee come il processo di stampa. Anche l'utilizzo dell'intestazione HTTP fa parte di REST e mantiene pulito l'URI.

Basta aggiungere un parametro al GET dell'URI corrente

È abbastanza tipico usare un URI per più azioni.

Se stai parlando della stessa risorsa ma di un'azione diversa, la definiresti come parametro.

/ Cliente / {id}? Print = true

Quindi, quando si definisce il metodo GET, si rileva la presenza del parametro di stampa e lo si gestisce in modo diverso.

Il REST è definito nel modo seguente:

• POST - Crea un record, risorsa o risorsa
• PUT: aggiornamento, record, risorsa o risorsa
• ELIMINA: rimuove un, record, risorsa o risorsa

GET, d'altra parte, è pensato per essere utilizzato in diversi modi perché in genere ci sono molte forme diverse che una risorsa può essere recuperata. Questo è anche il motivo per cui le richieste GET sono rappresentate come una stringa di query. Se si stesse lavorando con una risorsa di database, si sarebbe letteralmente recuperato una vista tramite una query, ma REST è intenzionalmente astratto a un livello superiore perché è progettato per gestire molti tipi diversi di risorse.

La specifica REST è piuttosto lungimirante, anche se solo recentemente le API stanno iniziando a usarlo pesantemente.

Se sei interessato a saperne di più sui protocolli REST ti consiglio vivamente di leggere " Haters Gonna Hate HATEOAS ".

Aggiornare:

@Shauna ha sottolineato un buco interessante nel mio ragionamento. Non esiste un vero modo giusto e molte forme sono considerate accettabili. Ci ho pensato un po 'di più e poiché l'uso previsto è quello di trasformare i dati in una rappresentazione diversa, ha senso definire la trasformazione come un nuovo tipo MIME.

Ad esempio, potresti rappresentare l'URI come:

/customer/{id}+print

Dove è possibile impostare la risposta Content-Type su text / html + print. In questo modo avresti anche la possibilità di definire più trasformazioni in futuro.

Per esempio:

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

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

Ad ogni modo, tutte le forme sono accettabili. L'implementazione che decidi dipende più dalle preferenze personali e dalle capacità del tuo server.

A parte: vorrei chiarire dal momento che sembra esserci un po 'di confusione. Il parametro di query "print" e / o il tipo di contenuto vengono utilizzati per specificare la modalità di trasformazione della risorsa. Non come attivare un lavoro di stampa fisico. Per motivi di sicurezza, l'accesso a livello hardware è sempre lasciato all'utente / client / browser.