Ecco un ulteriore paio di convenzioni in materia di collegamenti e percorsi di progettazione in API REST che potrebbe aiutare:
1. Percorso Parametri vs Query String
- params percorso (
/parent/child1;child2) sono cool ma le stringhe di query possono esprimere quanto possono essere i parametri del path, sono standard ed espliciti. es:
/parent?id=child1&id=child2- o
/parent?id=child1;child2 ... ecc
2.Plurale o singolare
Uso il plurale per ogni collezione (o un tavolo, o una cartella) è buono in quanto implica che la risorsa è una lista di altri risorsa
/users, /users/user1, /users?active=true
risorsa Nesting : Predefinito per non annidare a meno che non vi sia una relazione forte
Se una risorsa figlio candidato può esistere indipendentemente dal genitore, non vi è alcun punto nel raggruppamento perché potrebbe finire con più percorsi per la stessa cosa:
/departments/{departments}/employees/{employee}/branch-offices/{branch}/employees/{employee}/employees/{employee}
Con quest'ultimo si può fare tutto il resto:
- tutto impiegati in un reparto
/employees?department={department}
- tutti i dipendenti in un ramo
/employees?branch={branch}
3. Utilizzare nidificazione solo sui rapporti di forza
Quando la risorsa nidificato non può esistere al di fuori del genitore (Composition in termini UML per esempio)
/books/{book}/pages/{page} Non si cercherebbe mai una pagina senza specificare un libro/players/{player}/stats} (aga in, dipende dal vostro modelli di dominio)
4. Bene ok ... Utilizzare percorsi nidificati sui rapporti non così forte troppo, ma trattarli come alias
Naturalmente si potrebbe desiderare di fare nidificare anche se non esiste una relazione forte o un ciclo di vita delle risorse legato (l'esempio di dipartimento/dipendente) per qualche ragione (DX, forse la leggibilità?). se lo fai, forse si dovrebbe prendere in considerazione il percorso nidificato come un alias solo:
- per
/departments/{department}/employees
- riscrittura interno
/employees?department={department}
5. Se si vuole hateoas, poi il design percorso dovrebbe non essere la priorità assoluta
D'altra parte, la leggibilità del client non è importante se si desidera abbracciare REST HATEOAS. I client API non dovrebbero indovinare i tuoi collegamenti o avere i loro modelli codificati. Invece, la tua API fornisce collegamenti seguiti dai clienti.Esempio:
La radice percorso potrebbe per esempio la lista tutti i link principali:
GET/
200 OK
Content-Type: application/json
{
links:{
"employees":"/url-for-employees{?department,branch,name}"
"departments":"/them-deps"
}
}
I collegamenti sono volutamente brutta in questo esempio. Il numero dipendenti con chiave è in realtà un URL template con parametri facoltativi.
L'API client cerca poi per il collegamento con chiave employee, (in questo caso/url-per-dipendenti) - indipendentemente da quello che sembra - e lo chiama:
GET /url-for-employees
200 OK
Content-Type: application/json
Link: </url-for-employees{?department,branch,name}>; rel="search",
</url-for-employees?page=2>; rel="next"
['body is an array containing the first set/page of employees']
Avviso l'intestazione link contenente 2 link, uno per la ricerca e uno per ottenere la pagina successiva di dipendenti (rel = next ").
I vantaggi di HATEOS sono fuori portata qui ma almeno uno è che sei libero di riorganizzare il tuo percorsi senza rompere i client API
5. Ultimo, provare cose sul file system
Uno potrebbe utilizzare il file system di delineare/deridere un API riposante: creare cartelle, file (e forse link simbolici/alias/scorciatoie) sul disco rigido, sfogliali, cambiali, lava risciacquo e ripeti fino a quando sei felice con la struttura :)
$ mkdir myapi
$ cd myapi
$ touch index.json
$ mkdir employees
$ touch employees/index.json
$ touch employees/smith.json
$ mkdir departments
$ touch departments/index.json
$ touch departments/accounting.json
$ mkdir departments/accounting
$ mkdir departments/accounting/employees
$ ln -s employees/smith.json departments/accounting/employees/smith.json
$ ls -l departments/accounting/employees
smith.json -> employees/smith.json
Farà qualche controllo basato sul deptOrOrgId? Come fare qualche funzione se è departmentID e fare qualcos'altro se il suo OrganisationID – Adheep
è puramente per ottenere l'indirizzo di un dipartimento. ex, per ottenere l'indirizzo di un dipartimento IT è sufficiente l'ID del dipartimento IT. Se viene fornito l'ID dell'organizzazione, devo ottenere l'elenco dei reparti e trovare il reparto IT al suo interno e restituire l'indirizzo del reparto IT. quindi il mio parametro url dovrebbe accettare DepartmentId o organisationId per restituire un indirizzo di reparto. – rsudha
Il modo standard per gestire ciò è avere un URL costante 'http: // nomehost/[percorso contesto]/get? DepartmentId = [x] & organisationId = [y]' In base al valore disponibile in departmentId e organizationId, devi gestirlo nella tua implementazione come hai menzionato nel commento sopra. – Adheep