Alcuni dubbi su una corretta progettazione dell'API REST

Question

Alcuni dubbi su una corretta progettazione dell'API REST

#1 da (10 voti)

5

Sto costruendo un'API JSON REST per la mia applicazione e ho qualche dubbio sul design stesso. La mia applicazione ha organizzazioni e anche attrezzature che appartengono alle organizzazioni. Questo sarebbe un esempio dell'API delle organizzazioni:

/organizations:

Loads all the organizations from the application

/organizations/{id}:

Loads a specific organization by id

Questo sembra abbastanza chiaro. Comunque ora voglio accedere all'apparecchiatura, che è accessibile tramite id o codice. L'ID è univoco per l'applicazione, mentre il codice è univoco per organizzazione. Alcune scelte:

/organizations/{id}/equipment:

Loads the equipment by organization. This seems quite clear to me

/organizations/{idOrg}/equipment/{idEquip}:

Equipment by id. Isn't the organization id quite redundant here?

/organizations/{idOrg}/equipment/code/{code}:

Seems it makes sense, but probably would be better to pass code as a parameter.

/organizations/{idOrg}/equipment?id={idEquip}:

Best choice?

/organizations/{idOrg}/equipment?code={code}:

Best choice?

A mio parere, i metodi qui sotto sembrano migliori solo per l'acquisizione di apparecchiature (anche se restituiscono una lista, mentre il metodo dovrebbe restituire un singolo valore o nulla). Tuttavia, ho ancora più relazioni con le apparecchiature, che questi metodi non sembrano adeguati. Ad esempio come estendere l'API per integrare i metodi per caricare i file per ogni apparecchiatura?

Aggiorna

Si dovrebbe considerare che le organizzazioni sono strutturate gerarchicamente, quindi abbiamo alberi organizzativi e se org1 contiene org2 e una apparecchiatura appartiene a org2, essa appartiene anche a org1.

design api rest

posta Xtreme Biker 01.12.2016 - 12:42

fonte

1 risposta

Leggi altre domande sui tag design api rest

Evitare blocchi quando si chiama un'API nativa Gestione delle eccezioni di cui non sono a conoscenza

score 10 · Accepted Answer

Quando consideri REST è importante comprenderlo e progettarlo mentre stai intraprendendo azioni contro una risorsa nel luogo e non come effettuare una chiamata di funzione remota.

Capisco che sei in dubbio con il tuo design per "Equipment by id".

Mi piacerebbe essere la chiamata api come questa -

/organizations/{idOrg}/equipment/{idEquip}

Motivi che sono -

Con questo design, stai chiaramente affermando che stai cercando una particolare attrezzatura in un'organizzazione.
Ora puoi anche chiamare altri verbi come PUT , DELETE ecc. contro la stessa risorsa e rispettare i principi REST. Ad esempio, chiameresti la stessa API con delete per eliminare questa risorsa o chiamarla con put per aggiornarla e inviare i dati aggiornati nel corpo della richiesta.
E come hai detto Id per l'organizzazione sembra ridondante, ma in realtà non lo è. Quello che stiamo dicendo con questo è che prendermi un'organizzazione con questo ID e darmi la sua entità correlata, cioè un'apparecchiatura. Probabilmente, le apparecchiature isolate potrebbero non avere senso per l'API se sono richieste informazioni correlate dall'organizzazione. E nel caso tu voglia restituire solo un'apparecchiatura con il suo id, allora dovresti avere un'APP separata, qualcosa del tipo -

/equipments/{idEquip}
I parametri della stringa di query sono suggeriti quando si desidera ulteriormente analizzare le risorse con filtro, impaginazione o ordinamento, ecc. Ad esempio:

/organizations/{idOrg}/equipments/?type="heavy"

Aggiornamento (per Q e commenti aggiornati) - A volte diventa difficile visualizzare il nostro design della API in termini di codice. Per semplificare, se un'apparecchiatura fa parte di un'organizzazione, allora l'api dovrebbe ottenere quell'attrezzatura, ovviamente in relazione a quella particolare organizzazione.

Per aggiungere un nuovo equipaggiamento a org3 userai put su org3 vale a dire /organizations/3 . Per modificare ed equipaggiare già in org3 userai put su attrezzature cioè /organizations/3/equipment/1 . E se hai bisogno di aggiungere una nuova apparecchiatura in modo indipendente, chiameresti post su apparecchiature i.e. /equipment

Puoi anche considerare la gerarchia degli oggetti per renderla più intuitiva e logica, se necessario

Suggerisci di leggere questa serie su Restful Api design