Les meilleures pratiques sur l'utilisation des URIs comme valeur de paramètre dans les appels REST

Question

Je suis la conception d'une API REST où certaines ressources peuvent être filtrées par des paramètres de la requête. Dans certains cas, ces valeurs de filtre seraient les ressources de la même API REST. Cela rend assez long et assez illisible URIs. Bien que ce n'est pas trop d'un problème en soi parce que les URIs sont destinés à être créés et manipulés par programmation, il en fait une mise au point douloureux. Je pensais à permettre des raccourcis vers URIs utilisés comme valeurs de filtre et je me demande si cela est autorisé selon l'architecture REST et s'il y a des meilleures pratiques.

Par exemple:

J'ai une ressource qui me fait des classes Java. Ensuite, la demande suivante me donner toutes les classes Java:

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

Supposons que je veux que tous les sous-classes de la classe Java Collection, alors j'utiliser la requête suivante:

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

Cette demande me retourner Vector, ArrayList et toutes les autres sous-classes de la classe Collection Java.

Ce URI est assez long cependant. Je pouvais déjà le raccourcir en permettant hs comme un alias pour has-supertype. Cela me donnerait:

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

Une autre façon de permettre URIs plus courtes serait de permettre des alias pour les préfixes URI. Par exemple, je pourrais définir comme class un alias pour le préfixe URI http://example.org/api/v1/class/. Ce qui me donnerait la possibilité suivante:

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

Une autre possibilité serait de supprimer l'alias de classe préfixe entièrement et toujours la valeur du paramètre avec http://example.org/api/v1/class/ car cela est la seule chose que je soutiendrais. Transformerait la demande de tous les sous-types de Collection dans:

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

Faites ces « » de la simplification URI demande initiale conforme toujours aux principes d'une architecture REST? Ou je ne vais juste à côté de la fin profonde?

ADDENDA: Il pourrait y avoir plus d'un filtre dans l'URI à la fois. Soit en tant que paramètres différents, ou comme une liste de valeurs pour un paramètre unique. Pensez le long des lignes de « Toutes les classes qui mettent en œuvre l'interface X et / ou Y Interface » ou « Toutes les classes qui mettent en œuvre l'interface X et sont dans le paquet A.B.C » (où les paquets seraient également adressable à un URI comme http://example.org/api/v1/packages/a/b/c)

Answer 1

J'aller pour faire:

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

renvoie une liste de liens vers d'autres entrées dans votre API RESTful, un pour chaque sous-classe directe. Je voudrais aussi faire que les informations disponibles dans le cadre du descripteur retourné par:

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

(Cela comprend également un lien vers la requête spécifique précédente.)