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)
I’d go for making:
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:
(That would also include a link to the preceding specific query.)