3dna/api_docs — pull request #24 by mjuhasz (2014-04-23 20:35:52+00:00)
Title: Use query string instead of GET request body

@DavidHuie @arionhardison Support for GET request body is limited in frameworks and it is a questionable practice to rely on it.

We are really liberal by supporting the GET request body on our end (Rails does that for us, for free). However clients may find that *their* library does not support GET request bodies therefore we should be consistent and use query strings in the documentation for GET requests.
- - -
###### For the record, here is the email I wrote about this earlier:

HTTP GET requests are not supposed to have bodies. It is not explicitly forbidden by the specification in general but for the purpose we use it for, it is.

One of the principal authors of the HTTP specification, Roy Fielding summarized it that you can send a request body with GET but if it has meaning, that is, the response depends on the request body (which is the case for the People API Search endpoint), then you are violating the HTTP specification.

We are pretty consistent on our GET type of endpoints stating what the parameters are and then we give an example using those in a query string.

The Search endpoint is an exception. We state what the parameters are but then (unlike other GET endpoints) we give an example with a GET request body.

Rails does not make any distinction between query string parameters (those after a "?" in the URL) and POST parameters, and both are available in the params hash in the controller.

We should give an example using a query string, something like:

`https://abeforprez.nationbuilder.com/api/v1/people/search?first_name=Chuck`

The complicated bit is that we accept a nested hash for searching by custom values. They encode like this:

`{custom_values: {favorite_movie: "Star Wars"}}`

becomes:

`custom_values%5Bfavorite_movie%5D=Star+Wars`

(One way to easily encode nested hashes is using `to_query` in Rails).

I understand this is suboptimal but encouraging people to use the request body in the GET is not ideal either (framework support is limited, surprises may come).