HTTP POST with URL query parameters -- good idea or not

Question

I m designing an API to go over HTTP and I am wondering if using the HTTP POST command  but with URL query parameters only and no request body  is a good way to go  Considerations    quot Good Web design quot  requires non-idempotent actions to be sent via POST  This is a non-idempotent action  It is easier to develop and debug this app when the request parameters are present in the URL  The API is not intended for widespread use  It seems like making a POST request with no body will take a bit more work  e g  a Content-Length  0 header must be explicitly added  It also seems to me that a POST with no body is a bit counter to most developer s and HTTP frameworks  expectations   Are there any more pitfalls or advantages to sending parameters on a POST request via the URL query rather than the request body  Edit  The reason this is under consideration is that the operations are not idempotent and have side effects other than retrieval  See the HTTP spec   In particular  the convention has been established that the GET and HEAD methods SHOULD NOT have the significance of taking an action other than retrieval  These methods ought to be considered  quot safe quot   This allows user agents to represent other methods  such as POST  PUT and DELETE  in a special way  so that the user is made aware of the fact that a possibly unsafe action is being requested      Methods can also have the property of  quot idempotence quot  in that  aside from error or expiration issues  the side-effects of N  gt  0 identical requests is the same as for a single request  The methods GET  HEAD  PUT and DELETE share this property  Also  the methods OPTIONS and TRACE SHOULD NOT have side effects  and so are inherently idempotent

User · Answer

It would be fine to use query parameters on a POST endpoint, provided they refer to already existing resources.

For example:

POST /user_settings?user_id=4
{
  "use_safe_mode": 1
}

The POST above has a query parameter referring to an existing resource. The body parameter defines the new resource to be created.

(Granted, this may be more of a personal preference than a dogmatic principle.)

User · Answer

The REST camp have some guiding principles that we can use to standardize the way we use HTTP verbs  This is helpful when building RESTful API s as you are doing   In a nutshell  GET should be Read Only i e  have no effect on server state  POST is used to create a resource on the server  PUT is used to update or create a resource  DELETE is used to delete a resource   In other words  if your API action changes the server state  REST advises us to use POST PUT DELETE  but not GET   User agents usually understand that doing multiple POSTs is bad and will warn against it  because the intent of POST is to alter server state  eg  pay for goods at checkout   and you probably don t want to do that twice   Compare to a GET which you can do an often as you like  idempotent

User · Answer

Everyone is right  stick with POST for non-idempotent requests   What about using both an URI query string and request content  Well it s valid HTTP  see note 1   so why not    It is also perfectly logical  URLs  including their query string part  are for locating resources  Whereas HTTP method verbs  POST - and its optional request content  are for specifying actions  or what to do with resources  Those should be orthogonal concerns   But  they are not beautifully orthogonal concerns for the special case of ContentType application x-www-form-urlencoded  see note 2 below    Note 1  HTTP specification  1 1  does not state that query parameters and content are mutually exclusive for a HTTP server that accepts POST or PUT requests  So any server is free to accept both  I e  if you write the server there s nothing to stop you choosing to accept both  except maybe an inflexible framework   Generally  the server can interpret query strings according to whatever rules it wants  It can even interpret them with conditional logic that refers to other headers like Content-Type too  which leads to Note 2   Note 2  if a web browser is the primary way people are accessing your web application  and application x-www-form-urlencoded is the Content-Type they are posting  then you should follow the rules for that Content-Type  And the rules for application x-www-form-urlencoded are much more specific  and frankly  unusual   in this case you must interpret the URI as a set of parameters  and not a resource location   This is the same point of usefulness Powerlord raised  that it may be hard to use web forms to POST content to your server  Just explained a little differently    Note 3  what are query strings originally for  RFC 3986 defines HTTP query strings as an URI part that works as a non-hierarchical way of locating a resource   In case readers asking this question wish to ask what is good RESTful architecture  the RESTful architecture pattern doesn t require URI schemes to work a specific way  RESTful architecture concerns itself with other properties of the system  like cacheability of resources  the design of the resources themselves  their behavior  capabilities  and representations   and whether idempotence is satisfied  Or in other words  achieving a design which is highly compatible with HTTP protocol and its set of HTTP method verbs   -   In other words  RESTful architecture is not very presciptive with how the resources are located    Final note  sometimes query parameters get used for yet other things  which are neither locating resources nor encoding content  Ever seen a query parameter like  PUT true  or  POST true   These are workarounds for browsers that don t allow you to use PUT and POST methods  While such parameters are seen as part of the URL query string  on the wire   I argue that they are not part of the URL s query in spirit

User · Answer

You want reasons   Here s one   A web form can t be used to send a request to a page that uses a mix of GET and POST   If you set the form s method to GET  all the parameters are in the query string   If you set the form s method to POST  all the parameters are in the request body   Source  HTML 4 01 standard  section 17 13 Form Submission

User · Answer

I agree - it s probably safer to use a GET request if you re just passing data in the URL and not in the body   See this similar question for some additional views on the whole POST GET concept

User · Answer

If your action is not idempotent  then you MUST use POST   If you don t  you re just asking for trouble down the line   GET  PUT and DELETE methods are required to be idempotent   Imagine what would happen in your application if the client was pre-fetching every possible GET request for your service     if this would cause side effects visible to the client  then something s wrong   I agree that sending a POST with a query string but without a body seems odd  but I think it can be appropriate in some situations   Think of the query part of a URL as a command to the resource to limit the scope of the current request   Typically  query strings are used to sort or filter a GET request  like  page 1 amp sort title  but I suppose it makes sense on a POST to also limit the scope  perhaps like  action delete amp id 5

User · Answer

I would think it could still be quite RESTful to have query arguments that identify the resource on the URL while keeping the content payload confined to the POST body   This would seem to separate the considerations of  What am I sending   versus  Who am I sending it to

User · Answer

From a programmatic standpoint  for the client it s packaging up parameters and appending them onto the url and conducting a POST vs  a GET   On the server-side  it s evaluating inbound parameters from the querystring instead of the posted bytes   Basically  it s a wash   Where there could be advantages disadvantages might be in how specific client platforms work with POST and GET routines in their networking stack  as well as how the web server deals with those requests  Depending on your implementation  one approach may be more efficient than the other  Knowing that would guide your decision here   Nonetheless  from a programmer s perspective  I prefer allowing either a POST with all parameters in the body  or a GET with all params on the url  and explicitly ignoring url parameters with any POST request  It avoids confusion

[rest] HTTP POST with URL query parameters -- good idea or not?

Examples related to rest

Examples related to http