Best practices on using URIs as parameter value in REST calls.

Question

I am designing a REST API where some resources can be filtered through query parameters. In some cases, these filter values would be resources from the same REST API. This makes for longish and pretty unreadable URIs. While this is not too much of a problem in itself because the URIs are meant to be created and manipulated programmatically, it makes for some painful debugging. I was thinking of allowing shortcuts to URIs used as filter values and I wonder if this is allowed according to the REST architecture and if there are any best practices.

For example:

I have a resource that gets me Java classes. Then the following request would give me all Java classes:

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

Suppose I want all subclasses of the Collection Java class, then I would use the following request:

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

That request would return me Vector, ArrayList and all other subclasses of the Collection Java class.

That URI is quite long though. I could already shorten it by allowing hs as an alias for has-supertype. This would give me:

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

Another way to allow shorter URIs would be to allow aliases for URI prefixes. For example, I could define class as an alias for the URI prefix http://example.org/api/v1/class/. Which would give me the following possibility:

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

Another possibility would be to remove the class alias entirely and always prefix the parameter value with http://example.org/api/v1/class/ as this is the only thing I would support. This would turn the request for all subtypes of Collection into:

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

Do these "simplifications" of the original request URI still conform to the principles of a REST architecture? Or did I just go off the deep end?

ADDENDUM: There might be more than one filter in the URI at once. Either as different parameters, or as a list of values for a single parameter. Think along the lines of "All classes that implement Interface X and/or Interface Y" or "All classes that implement Interface X and are in package A.B.C" (where packages would also be addressable to a URI like http://example.org/api/v1/packages/a/b/c)

Answer 1

I'd go for making:

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

return a list of links to other entries in your RESTful API, one for each direct subclass. I'd also make that information available as part of the descriptor returned by:

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

(That would also include a link to the preceding specific query.)