WebAPI - Advantages of Routes over Parameters

Question

I've been developing a web service using web API and originally I was using exclusively routes to accessing different methods such as the following:

Example URL

http://host/api/values/param1/param2

However after playing around with some options, I found that this didn't provide me near the flexibility I needed with different parameters options and switched to using parameters:

Example URL

http://host/api/values?p1=param1&p2=param2

I found that this gave me many advantages over using the routes, such as:

Same types of parameters can be mapped to different routes:

http://host/api/values?paramX1=string&paramX2=string2

Is a different route than:

http://host/api/values?paramY1=string&paramY2=string2

But using string routes they can't be differentiated (or can they?):

No need for URL encoding

With parameters I can do this:

http://host/api/values?searchCriteria=*101* 

But can't do this with routes:

http://host/api/values/*101* <-- ERROR!

URLs are more easily understood (Opinion, ignore if you'd like)

Knowing that the parameter you are passing in is a searchCriteria or a bookTitle can be very helpful. This seems to be more opinion based, but I see it as a major benefit.

With this in mind I have two questions:

Why is the convention for web API to use routes instead of querystring parameters?

And

Are there benefits to using routes over querystring parameters that I'm just missing?

To be clear, I'd like technical programmatic benefits with something you can achieve using routes instead of parameters, not just "I like these better".

Answer 1

Routing parameters make the URLs less clunky and indicate that the values are an integral part of the URL.

In RESTful services a common convention is to have parameters that identify a resource a part of the URL path using routing parameters. For example:

http://example.com/product-store/product/10

The URL would identify a product with ID # 10 in a product store. If it was an SEO friendly e-commerce site instead of a web service, the URL might have had an additional parameter added for improved searching (Stack Overflow does that as well):

http://example.com/product-store/product/10/Microsoft-Windows-7-Professional

Query parameters would be more likely to get ignored, or given a lesser priority, by search engines.

However, query string parameters have a several advantages.

The URL path before the question mark is more limited in length. The limits depend on the browser, web server and even the DNS provider but it is recommended to keep the pre-querystring URL to 255 characters or less. The max full URL length (depending on the browser and the web server) can be anywhere from 2,000 characters to 100,000 characters or even more. So you can pass more data in the query string.

Just like you mentioned, due to DNS limitations the query parameters allow more flexibility with encoding/characters you can include.

So query parameters make a lot of sense for operation values that do not identify the resource. For example:

http://example.com/product-store/products?instock=true&zipcode=10001&pagesize=25&orderby=last+modified