URI query design

It is perfectly acceptable to use a query string as part of an API call; however, I would refrain from using this to pass data to the service. Instead the query should be used to perform actions such as:

• Paging
• Filtering
• Sorting

If we need to make a call to a controller, we discussed earlier that we should use a POST request as this is most likely a non-idempotent request. To pass data to the service, we should include the data inside of the body. However, we could use a query string to filter the action of the controller:

POST /sendStatusUpdateEmail?$group=admin 
{ 
  "message": "All services are now operational\nPlease accept our 
              apologies for any inconvenience caused.\n 
              The Kitten API team"
} 

In the preceding example, we would send a status update email with the message included in the body of the request, because we are using the group filter passed in the query string we could restrict the action of this controller to only send to the admin group.

If we had added the message to the query string and not passed a message body, then we would potentially be causing two problems for ourselves. The first is that the max length for a URI is 2083 characters. The second is that generally a POST request would always include a request body. Whilst this is not required by the HTTP specification, it would be expected behavior by the majority of your users.