Best practice sull'utilizzo degli URI come valore del parametro nelle chiamate REST

Question

Sto progettando un'API REST in cui alcune risorse possono essere filtrate tramite parametri di query. In alcuni casi, questi valori di filtro sarebbero risorse della stessa API REST. Questo rende URI piuttosto lunghi e illeggibili. Mentre questo non è troppo di per sé un problema perché gli URI sono pensati per essere creati e manipolati a livello di codice, ciò rende difficile il debugging. Stavo pensando di consentire scorciatoie agli URI usati come valori di filtro e mi chiedo se questo è permesso secondo l'architettura REST e se ci sono delle buone 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 io voglio tutte le sottoclassi della classe Collection Java, quindi vorrei usare la seguente richiesta:

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

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

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

Un altro modo per consentire URI più brevi potrebbe essere quella di consentire alias per prefissi URI. Ad esempio, potrei definire class come alias per il prefisso URI http://example.org/api/v1/class/. Il che mi avrebbe dato i seguenti possibilità:

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

Un'altra possibilità sarebbe quella di rimuovere l'alias di classe interamente ed anteporre sempre 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 conformi ai principi di un'architettura REST? O sono appena uscito dal profondo?

ADDENDUM: Potrebbe esserci più di un filtro nell'URI in una volta. Sia come parametri diversi, sia come elenco di valori per un singolo parametro. Pensate lungo le linee di "Tutte le classi che implementano l'interfaccia X e/o l'interfaccia Y" o "Tutte le classi che implementano l'interfaccia X e sono in pacchetto ABC" (dove i pacchetti sarebbe anche 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 collegamenti ad altre voci nella tua RESTful API, uno per ogni sottoclasse diretta. Mi piacerebbe anche fare che le informazioni disponibili come parte del descrittore restituito da: (. Che sarebbe anche includere un link alla precedente interrogazione specifica)

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