RESTifying URLs

Question

At work here, we have a box serving XML feeds to business partners. Requests for our feeds are customized by specifying query string parameters and values. Some of these parameters are required, but many are not.

For example, we've require all requests to specify a GUID to identify the partner, and a request can either be for a "get latest" or "search" action:

For a search: http://services.null.ext/?id=[GUID]&q=[Search Keywords]
Latest data in category: http://services.null.ext/?id=[GUID]&category=[ID]

Structuring a RESTful URL scheme for these parameters is easy:

Search: http://services.null.ext/[GUID]/search/[Keywords]
Latest: http://services.null.ext/[GUID]/latest/category/[ID]

But what how should we handle the dozen or so optional parameters we have? Many of these are mutually exclusively, and many are required in combinations. Very quickly, the number of possible paths becomes overwhelmingly complex.

What are some recommended practices for how to map URLs with complex query strings to friendlier /REST/ful/paths?

(I'm interested in conventions, schemes, patterns, etc. Not specific technologies to implement URL-rewriting on a web server or in a framework.)

Answer 1

Parameters with values? One option is the query string. Using it is not inherently non-restful. Another option is to use the semi-colon, Tim Berners-Lee talks about them and they might just fit the bill, allowing the URL to make sense, without having massively long paths.

Answer 2

You should leave optional query parameters in the Query string. There is no "rule" in REST that says there cannot be a query string. Actually, it's quite the opposite. The query string should be used to alter the view of the representation you are transferring back to the client.

Stick to "Entities with Representable State" for your URL path components. Category seems OK, but what exactly is it that you are feeding over XML? Posts? Catalog Items? Parts?

I think a much better REST taxonomy would look like this (assuming the content of your XML feed is an "article"):

• http://myhost.com/PARTNERGUID/articles/latest?criteria1=value1&criteria2=value2
• http://myhost.com/PARTNERGUID/articles/search?criteria1=value1&criteria2=value2

If you're not thinking about the entities you are representing while building your REST structure, you're not doing REST. You're doing something else.

Take a look at this article on REST best practices. It's old, but it may help.