使用子列表作为查询参数设计 REST 端点

Question

I have a get request that will give me a winner based on a list of inputs.

eg). [{rabbit:3, tiger:2}, {rabbit:1, donkey:3}, {bird:2}]. // the winner is {rabbit:1, donkey:3}

I would like to design a get end point that will take a list.

One way I could think of is like this:
/GET winner?rabbit,3?tiger,2&rabbit,1?donkey,3

A request param map would like like key:{rabbit,3?tiger,2}: value=[]

alternatively, I could do:

/GET winner?id1=rabbit,3?tiger,2&id2=rabbit,1?donkey,3

but I don't need the id information at all.

While this serves the purpose for what I need, I am wondering what would be the best way to represent query param with sub-object?

Answer 1

最明显的似乎是：

 GET /winner?rabbit=3&tiger=2&rabbit=1&donkey=3

Answer 2

There really isn't a great answer here.

As far as HTTP is concerned, any spelling that is consistent with the production rules described by RFC 3986 is fine .

If you have a representation that is easily described by a URI Template , then you (and your clients) can take advantage of the general purpose template libraries.

BUT... templates are not so flexible that they can be used to describe arbitrary message schemas . We've got support for strings, and lists (of strings) and associative arrays (of strings), and... that's pretty much it.

On the web, we might handle an arbitrary case using a form with a textarea control that accepts a string representation of the message; the browser would then create a key value pair, where the value is an encoded representation of the information in the text area.

So, for example, you could copy a string representation of a JSON document into the form, submit the form, and the browser would compose the matching query-part. On the server, you would reverse the process to get at the JSON document.

There's nothing particularly magic about using a key value pair, of course. Another possibility would be to ignore the key of the key value, and just use the properly encoded value as the query. Again, the server just reverses the process.

Another somewhat common attempt is to use key value pairs, treating the keys as "paths" - which is to say each key identifies a location in the original document, and the value indicates the information available at that location.

?/0/rabbit=1&/0/tiger=2&/1/rabbit=1&/1/donkey=3&/2/bird=2

In this example, the schema of the keys is based on JSON Pointer (RFC 6901), which is possible way to flatten hierarchical data into key value pairs. Which may not be "best", but is at least leaning in the direction of readily standardizable . (A standardized form would be an improvement, but I wasn't able to identify one).