REST Progettazione delle risorse

In termini di REST, specialmente se si applica il principio HATEOAS, non importa come si denomina il proprio URL. Il client non dovrebbe preoccuparsi degli URL, in quanto il server dovrebbe generare i collegamenti per il client.

Però ci sono alcune linee guida, i buoni URI REST dovrebbero essere un nome, non un verbo. Gli URI dovrebbero indirizzare gli oggetti, piuttosto che i metodi di indirizzamento.

L'API REST dovrebbe avere un numero limitato di verbi generici. Una buona API REST HTTP dovrebbe utilizzare correttamente i verbi HTTP, ad esempio utilizzare la richiesta GET per la richiesta di recupero e POST / PUT per la richiesta di modifica / creazione dei dati.

Alcuni esempi di buoni URL REST (uno dei due è una questione di gusti):

GET /employees/{employee_id}/vacations
GET /employees/{employee_id}?details=name,vacations

per ottenere l'elenco delle richieste di ferie e ferie relative al dipendente con un determinato employee_id.

Penso che le richieste di ferie dovrebbero semplicemente essere vacanze con status = in sospeso, tuttavia se decidi di voler esporre le richieste di ferie come risorsa separata, REST non ti impedisce di farlo. Finché il server produce gli URL per HATEOAS, in definitiva non importa se è esposto come URL separato.

Come da HATEOAS, le risorse delle liste di vacanze dovrebbero contenere un link (e un modulo) per creare una richiesta di ferie, che potrebbe essere simile a questa:

POST /employees/{employee_id}/vacations

e un elenco di URL che possono essere utilizzati per recuperare e aggiornare i dettagli di una vacanza, che può essere simile a questa:

GET /vacation/{vacation_id} (for retrieving detail)
PUT /vacation/{vacation_id} (for updating detail)
PATCH /vacation/{vacation_id} (alternative for updating detail)
(important: update requests must be conditional request/If-Match to protect against concurrent update)

I dipendenti non manager possono aggiornare solo le vacanze in attesa, se tentano di aggiornare le vacanze approvate, lo stato delle vacanze dovrebbe tornare in sospeso. Non manager non può modificare il campo dello stato direttamente altrimenti.

Il responsabile responsabile dell'approvazione della vacanza di un dipendente ha il permesso di impostare lo stato delle vacanze su approvato o rifiutato.

Un dipendente può ritirare la sua richiesta di ferie inviando la richiesta DELETE:

DELETE /vacation/{vacation_id}

che imposta lo stato delle ferie a ritroso.

Nota come tutte le richieste relative allo stesso oggetto sono eseguite contro lo stesso URL, ma con metodi HTTP diversi. Ciò fornisce al cliente il contesto in cui queste richieste ruotano attorno allo stesso oggetto. Possono usare questo, ad esempio, per implementare il caching, per invalidare automaticamente i dati memorizzati nella cache per lo stesso URL quando si effettua una richiesta POST / PUT / DELETE a quell'URL.

REST non si cura di quale ortografia si usa per gli identificatori di risorse. In genere gli utenti non si preoccupano neanche di Gli sviluppatori fanno - le identificazioni degli identificatori sono cugini per gli standard di codifica.

Nella tua API, dovresti davvero pensare alle tue risorse come risorse di integrazione , piuttosto che a quelle di dominio . Qual è il protocollo per il controllo del saldo delle ferie? Qual è il protocollo per l'aggiornamento del saldo delle ferie per un rapporto?

should I only have uri template like /vacation/vacations/{vacation_id} or would it be better to split

Separare i diversi identificatori per i casi d'uso che dovrebbero essere eseguiti da ruoli diversi è una buona idea, penso, poiché dovrebbe rendere più facile la messa in sicurezza dei diversi punti finali.

Should I expose VacationRequest as its own resource, or just as a specific state of a Vacation resource

Normalmente mi aspetto che tutti i moduli inviati vengano inviati allo stesso endpoint, con tutti i dati richiesti nel corpo del messaggio. Non deve essere così, ovviamente. I clienti non si preoccupano. Il tuo routing probabilmente non gli interessa molto. Potrebbero essere applicati problemi di autenticazione. Potrebbe essere utile avere gli identificatori di richiesta nei tuoi registri.