Is there a canonical/RESTful way to send query details to a server during a GET?

Question

I\'m designing a (more or less) RESTful internal web service running on ASP.NET and IIS. I want clients to be able to pass query details to the server when accessing large

Answer 1

I would use Option 4. It is difficult to put the query representation in json for a large search request into an url, especially against a search server. I agree, in that case it does not fit into a Restful style since the resources cannot be identified by the URI. REST is a guideline. If the scenario cannot be realized by REST then i guess do something that solves the problem. Here using POST is not restful but it seems to be the correct solution.

Answer 2

After thinking more about this, I am going to give another answer.

What do you mean, in estimated number of characters, when you state the JSON representations will be "relatively large"? IE can handle URLs over 2,000 characters. Will the queries ever get bigger than that? Because I think the querystring is the way to go. Right now I am working on a system that uses JSONP so we have no other option than to pass all data as a JSON package in the querystring and it works fine. Not only will using the GET verb be semantically correct, this will also include the feature of being able to bookmark URLs to the results. The users could easily share links to the data results through email or other electronic communication systems you use internally.

Answer 3

Use POST, and pass the queries/parameters as key-value pairs in the body as json. It also becomes easier in your asp.net code to translate the payload into a dictionary object.

Dictionary<string,object>

Answer 4

I'm not sure how much it would look "canonical" to you, but you could have a serious look at OData (open data protocol):

OData is a standardized protocol for creating and consuming data APIs. OData builds on core protocols like HTTP and commonly accepted methodologies like REST. The result is a uniform way to expose full-featured data APIs.

Even if you don't implement it as is, there are ideas that could be reused.

Specifically, OData defines batch processing. It's used for executing multiple operations sent in a single HTTP request. So, with OData, you have two choices:

1. use the GET + query string operation for queries that are not too long
2. use a POST + multipart body operation for bigger things.

More on maximum uri length in an OData context: OData Url Length Limitations

Also, many security devices (routers, firewall, etc.) will simply not let your option 1, 2 and 3 go through. GET + Body is unusual, GET + a big form value may get killed, and a custom HTTP verb is also very unusual.

Overall, I think the POST + body seems the best choice (whether it's strictly multipart - like in OData - or not is up to you)

Answer 5

The best way would be to serialize the search JSON object and pass it as a query parameter. Are you sure it will be too long for modern browsers and servers? Modern browsers and servers can handle pretty hefty GET query parameter lengths, thousands of characters.

Perhaps an extension header like X-Custom-Query-Parameters-JSON if objects are going to be more on the order of 8k characters.

How many characters would a serialized JSON object be in your particular case?

Some related questions about character limits:

What is the limit on QueryString / GET / URL parameters

Is there a practical HTTP Header length limit?

Answer 6

I'm not sure if this helps but even for all Quickbooks APIs, queries which return large resultsets like Read All, or a LINQ extender query which returns large JSON resultsets, we use GET with the relevant content type and encoding like ASCII. The request uses compressionFormat as None and response uses a GZIP compressionFormat. https://developer.intuit.com/apiexplorer?apiName=V3QBO