Sto creando un'API REST HTTP. Ho una vasta collezione di coppie chiave-valore, a /base-url .
Devo fornire la possibilità di ottenere e impostare valori per una chiave.
Il mio primo tentativo:
GET /base-url/{key}
PUT /base-url/{key}
Il problema è che questo richiede le ricette URL, che, a quanto ho capito, vanno contro i principi ipermediali di REST.
Quale è il solito modo di fornire un archivio di valori-chiave tramite un'API RESTful?
Questo è permesso da REST fino a quando i tuoi {key} URL sono rilevabili; per esempio se stai facendo
GET /base-url/
ha restituito un elenco di collegamenti ad altre risorse REST valide e tra questi c'erano /base-url/{key}
Il punto principale è che la conoscenza out-of-band non può essere richiesta da un'API conforme a REST; ma se un fornitore pubblica una specifica il cliente è certamente libero di andare direttamente a un URL che già conosce.
Ho trovato questo articolo di Roy Fielding utile per chiarire questi punti, in particolare
A REST API must not define fixed resource names or hierarchies (an obvious coupling
of client and server). Servers must have the freedom to control their own namespace.
Instead, allow servers to instruct clients on how to construct appropriate URIs, such
as is done in HTML forms and URI templates, by defining those instructions within
media types and link relations. [Failure here implies that clients are assuming a
resource structure due to out-of band information, such as a domain-specific standard,
which is the data-oriented equivalent to RPC's functional coupling].
Questo significa essenzialmente che se pubblichi una specifica e che il client / programmatore ha bisogno di quella per determinare gli URL validi, allora hai creato un'API ma non è un'API REST . Per conformarsi alla tesi di Roy Fielding che definisce REST, devi rendere quegli stessi URL rilevabili iniziando dalla radice.
Indipendente dall'implementazione di un negozio con valore-chiave o qualsiasi altra cosa: puoi usare HATEOAS per descrivere la tua api. Questo arricchisce le semplici informazioni sulla risorsa con meta -informazioni su cosa fare con la tua API. Quindi nel tuo esempio una chiamata a base fornisce una raccolta di chiavi e i loro valori:
GET /baseurl/
ti fornisce un set di risultati:
[
{
"links": {
"self": {
"href": "http://www.yoursite/base"
},
"item": [
{
"href": "http://www.yoursite/base/key1"
},
{
"href": "http://www.yoursite/base/key2"
},
{
"href": "http://www.yoursite/base/key3"
}
]
},
"content": [
{
"key": "key1",
"value": "value1",
"links": [
{
"self": {
"href": "http://www.yoursite/base/key1"
}
}
]
},
{
"key": "key2",
"value": "value2",
"links": [
{
"self": {
"href": "http://www.yoursite/base/key2"
}
}
]
},
{
"key": "key3",
"value": "value3",
"links": [
{
"self": {
"href": "http://www.yoursite/base/key3"
}
}
]
}
]
}
]
Un semplice GET contro il tuo baseurl mostra un elenco di elementi restituiti. Ciascuno con un collegamento (almeno) al singolo elemento (o più se si desidera correlare più chiavi ad altre risorse). Da quel punto in cui io, come consumatore, so che esiste una percentuale di risorse key3 dietro l'URL http://www.yoursite/base/key3 . Analogamente, so che potrei (eventualmente) usare i tipici verbi HTTP (HEAD, GET, PUT, POST, DELETE, PATCH). Tuttavia, posso interrogare tale ressurce per le sue capacità tramite OPZIONI -Richiesta. La sua risposta conterrebbe un Allow -Section, che mostra i verbi consentiti:
Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE
Se implementato in questo modo, la tua API diventa molto intuitiva e autoesplicativa (indipendente dalle risorse che offri).