StackOverflow2013

Note that there are some explanatory texts on larger screens.

plurals

POBest practices on using URIs as parameter value in REST calls
text
Body
copied!<p>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.</p> <p><em>For example:</em></p> <p>I have a resource that gets me Java classes. Then the following request would give me all Java classes:</p> <pre><code>GET http://example.org/api/v1/class </code></pre> <p>Suppose I want all subclasses of the <code>Collection</code> Java class, then I would use the following request:</p> <pre><code>GET http://example.org/api/v1/class?has-supertype=http://example.org/api/v1/class/collection </code></pre> <p>That request would return me <code>Vector</code>, <code>ArrayList</code> and all other subclasses of the <code>Collection</code> Java class.</p> <p>That URI is quite long though. I could already shorten it by allowing <code>hs</code> as an alias for <code>has-supertype</code>. This would give me:</p> <pre><code>GET http://example.org/api/v1/class?hs=http://example.org/api/v1/class/collection </code></pre> <p>Another way to allow shorter URIs would be to allow aliases for URI prefixes. For example, I could define <code>class</code> as an alias for the URI prefix <code>http://example.org/api/v1/class/</code>. Which would give me the following possibility:</p> <pre><code>GET http://example.org/api/v1/class?hs=class:collection </code></pre> <p>Another possibility would be to remove the class alias entirely and always prefix the parameter value with <code>http://example.org/api/v1/class/</code> as this is the only thing I would support. This would turn the request for all subtypes of <code>Collection</code> into:</p> <pre><code>GET http://example.org/api/v1/class?hs=collection </code></pre> <p>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?</p> <p>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 <code>http://example.org/api/v1/packages/a/b/c</code>)</p>

Querying!

Guidance

An individual column

Larger individual text columns get their own page to allow for proper reading.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload