Le migliori pratiche sull'utilizzo di URI come valore di parametro nelle chiamate REST

Question

Sto progettando un'API REST in cui alcune risorse possono essere filtrati attraverso parametri di query. In alcuni casi, questi valori di filtro sarebbero le risorse provenienti dalla stessa API REST. Questo rende piu 'lunga e URI abbastanza illeggibili. Anche se questo non è troppo di un problema in sé, perché le URI sono destinate ad essere creati e manipolati a livello di codice, si fa per un po 'di debug doloroso. Stavo pensando di consentire collegamenti a URI utilizzate come valori di filtro e mi chiedo se questo è permesso secondo l'architettura REST e se ci sono delle migliori pratiche.

Ad esempio:

Ho una risorsa che mi viene classi Java. Poi la seguente richiesta mi avrebbe dato tutte le classi Java:

GET http://example.org/api/v1/class

Supponiamo che voglio tutte le sottoclassi della classe Java Collection, quindi vorrei usare la seguente richiesta:

GET http://example.org/api/v1/class?has-supertype=http://example.org/api/v1/class/collection

La richiesta sarebbe tornato mi Vector, ArrayList e tutte le altre sottoclassi della classe Java Collection.

Questo URI è piuttosto lungo però. Potrei già accorciarla consentendo hs come alias per has-supertype. Questo mi darebbe:

GET http://example.org/api/v1/class?hs=http://example.org/api/v1/class/collection

URI Un altro modo per consentire più brevi sarebbe quello di consentire alias per prefissi URI. Ad esempio, ho potuto definire class come alias per il prefisso http://example.org/api/v1/class/ URI. Il che mi avrebbe dato la possibilità seguente:

GET http://example.org/api/v1/class?hs=class:collection

Un'altra possibilità sarebbe quella di rimuovere l'alias di classe tutto e sempre anteporre il valore del parametro con http://example.org/api/v1/class/ come questo è l'unica cosa che vorrei sostenere. Ciò si trasformerebbe la richiesta di tutti i sottotipi di Collection in:

GET http://example.org/api/v1/class?hs=collection

Fare queste "semplificazioni" della richiesta originale URI ancora conforme ai principi di un'architettura REST? O forse mi basta andare fuori di testa?

APPENDICE: Ci potrebbe essere più di un filtro nella URI in una sola volta. Sia come diversi parametri, o come un elenco di valori per un singolo parametro. Pensare lungo le linee di "Tutte le classi che implementano l'interfaccia X e / o Y Interface" o "tutte le classi che implementano l'interfaccia X e sono in pacchetto A.B.C" (dove i pacchetti potrebbero anche essere indirizzabile a un URI come http://example.org/api/v1/packages/a/b/c)

Answer 1

Mi piacerebbe andare per fare:

GET http://example.org/api/v1/class/java.util.Collection/subclasses

restituirà un elenco di link ad altre voci nella vostra API RESTful, uno per ogni sottoclasse diretta. Mi piacerebbe anche fare che le informazioni disponibili come parte del descrittore restituito da:

GET http://example.org/api/v1/class/java.util.Collection

(Che sarebbe anche includere un collegamento alla query specifica precedente.)