My main criteria for choosing the URI is keeping to mainstream conventions. I want the API to be as intuitive as it can be for the developers consuming it.
Il fatto che questo sia così importante implica che la tua API potrebbe non essere effettivamente RESTful. Con HATEOAS implementato, un client potrebbe leggere questi link da un'altra risposta servita dalla tua API senza la necessità per un essere umano di mai leggere l'URL (a meno che non si analizzi i log). La pagina di esempio che rimandi a indica che l'obiettivo della tua documentazione in un'API REST dovrebbe essere sulle rappresentazioni piuttosto che sugli endpoint .
So, what makes an API a good API? We will use the following tenets gathered from various authors across the web:
...
- Has documention sufficient to guide the user of the API (and that does not redundantly document REST principles but instead focuses on representations, validation rules, security, etc.).
- ...
- Requires knowledge only of a single URI entry point and access to documentation specifying the media types. (Note this is an hypermedia 'stretch goal'.)
Per quanto riguarda REST, semplicemente non conta come tutti, ma un numero molto basso di endpoint dovrà essere noto a un programmatore che scrive un client per la propria API. Il resto dovrebbe essere libero di cambiare e non deve essere necessariamente leggibile. Che siano leggibili o meno, è una questione di preferenza e non un principio REST.
Detto questo, dovresti scegliere quello che si adatta alla semantica della tua API.
Inoltre, è altamente improbabile che tu abbia effettivamente bisogno che la tua API sia veramente RESTful.
Se scegli di fornire un numero di endpoint insieme alla documentazione per le persone che scrivono programmi che raggiungono questi endpoint, ti suggerisco di andare con users/{id}/servers .
Perché? Mi sembra più utile.
Se la tua API è RESTful, letteralmente non importa. Sarai libero di cambiarlo da users/{id}/servers a /jabber{id}wocky ei client non dovrebbero rompersi finché capiscono le rappresentazioni che stai restituendo e le rappresentazioni contengono i giusti collegamenti e abbastanza metadati per il client dell'applicazione per capire cosa il link rappresenta.
Se la tua API è solo un'API Web generica che serve i dati su HTTP senza sovrascrivere la semantica dei metodi HTTP (diciamo, un Livello 2 in Richardson's Maturity Model ), gli URL degli endpoint contano di più. Penso che users/{id}/servers appaia più robusto. Se si decide di rendere possibile che un utente abbia più server assegnati (qualunque cosa ciò significhi nel proprio dominio aziendale), questo dovrebbe essere più semplice da estendere. Se le persone iniziano a scrivere client che aspettano users/{id}/server , diventerà strano se introdurrai più server per utente. La semantica di questo endpoint dovrà cambiare in qualche modo (sarà solo il primo server? Primo basato su quali criteri?). Ti prego che questa è una ipotesi selvaggia da parte mia. È difficile prendere questo tipo di decisione senza comprendere lo scopo della tua API e le proprietà di tali risorse.
Inoltre, questa scelta può essere importante o meno in termini di manutenibilità a seconda di come ci si avvicina al controllo delle versioni dell'API. Ma questo è un argomento molto ampio da solo.