To save typing rename HttpRequest#queryParameters to HttpRequest#params

[DartBot]

This issue was originally filed by @MarkBennett

---

What steps will reproduce the problem?

1. Edit a Dart file in a plain text editor
2. Type queryParameters.
3. Realize you just wasted 9 keystrokes.

What is the expected output? What do you see instead?

    I would expect to only need to type params, but instead had to type queryParameters. I would expect details of this function to be included in the source code documentation, and for the function name to be more concise.

What version of the product are you using? On what operating system?

    Version 0.1.0.201204121423, Build 6479
    Dart SDK version 6478, Dartium version

Please provide any additional information below.

    As an enhancement to this bug, consider displaying function documentation in the autocomplete in the Dart Editory.

[madsager]

cc @sgjesse.
Added Area-IO, Triaged labels.

[sgjesse]

Having short and simple and descriptive names is definitely one of design criteria for the dart:io APIs.

In relation to queryParameters the reason for the long name is that we need to support handling of parameters from form posts as well as from the query string. Handling of POSTs with content type application/x-www-form-urlencoded will be supported soon (we will have to see about multipart/form-data - especially if file uploads are involved)‎, and to distinguish these parameters from the query string using getter formParameters was intended.

I agree that both are long names, so maybe "query" and "form" are better names.

Alternatively we could use "params" as suggested together with "form".

[DartBot]

This comment was originally written by @MarkBennett

---

What about combining POST and GET parameters into a single
HttpRequest#params, but keeping the longer names for accessing the GET and
POST params separately? This is how it's done in Rails and Pylons. I
believe it's also the same in Node but will need to check.

I would really like to focus on keeping the Dart API simple.

[DartBot]

This comment was originally written by @seaneagan

---

I would suggest to change HttpRequest#uri from String to Uri, and then remove HttpRequest#{path,queryParameters,queryString}, and then fix issue #2645. Then all uri related information is available in one place:

interface HttpRequest {
  //...
  final Uri uri;
}

Then you can just do:

// see issue #2645
request.uri.query['foo']
request.uri.queryString

request.uri.path

and in the case you need the String uri itself, just do:

request.uri.toString()

or if you are using string interpolation it's even easier...

"request uri is: ${request.uri}"

...since that calls toString implicitly.

[DartBot]

This comment was originally written by @MarkBennett

---

I like the idea of combining the query parameters with the uri class, however what about POST parameters? Would they be stored in a separate accessor still?

Perhaps there's an interface which both HttpRequest and uri could implement instead, only the HttpRequest would also include POST params?

[DartBot]

This comment was originally written by @seaneagan

---

Yes, Map<String, List<String>> or [List]MultiMap<String, String> would make sense for both query and form parameters. I think since form POSTing is being used less and less all the time due to AJAX etc., it's best to keep the form parameters separate:

interface HttpRequest {
  //...
  final Uri uri;
  final Map<String, List<String>> form;
}

In case someone does want to access params independently of whether they came from a form or the URI, issue #2644 would be useful:

var params = request.form.merge(request.uri.query);
// or vice-versa
var params = request.uri.query.merge(request.form);

...depending on whether you want query or form parameters to take precedence. Not sure if it is common to combine values from a query parameter and form parameter both with the same name, but if so, then a MultiMap#merge would work better.

[DartBot]

This comment was originally written by @MarkBennett

---

Can you explain this assertion a bit more as it doesn't match my
experiences at all. Why do you say people are using POSTing less and less?
It's easy to do POST requests from AJAX and I often do them more as they're
an essential part of designing RESTful API's. Generally, the rule I follow
to distinguish between POST and GET methods when designing an API is
simple. POST requests will modify the business data in some meaningful way
(creating new objects, changing existing ones) while GET requests are read
only. There are exceptions such as logging API usage or logging in general
but using POST for changes to the model is a simple way to create safer and
more discoverable APIs.

I like the idea of exposing the form and query parameters seperately, but I
still think there's a case for a single accessor that captures both. This
is how parameters are implemented in Rails, node, and Pylons and has made
writing server code much simpler. In most use cases, a user doesn't care if
a parameter was received from a query string or POST, just that it was
received.

[DartBot]

This comment was originally written by @seaneagan

---

I am under the impression that POST parameters only exist when an HTML form is submitted from a web browser (resulting in an application/x-www-form-urlencoded request). And I am asserting that submitting HTML forms is being replaced by ajax and other methods which do not cause a page reload. So I think it is somewhat of a minority use case, which may want to be deprecated at some point, and thus should be separated out.

[DartBot]

This comment was originally written by @MarkBennett

---

Ah, ok I think I see the confusion here.

AJAX, or more specifically XHR, allows you to make HTTP requests from
JavaScript code. The underlying requests can use any HTTP method available
to the web browser. This includes HTTP GET, PUT, POST, HEAD and other
methods. Though the page doesn't reload, pages using AJAX calls make
extensive use of HTTP POST requests.

If you'd like to learn more about AJAX or the requests made on a webpage,
an easy way to see it in action is to open up the Developer Tools in Chrome
and go to the network tab. Navigate to a page that makes extensive use of
AJAX (like Gmail.) You may need to reload the page but once you do you'll
see the network tab filling with AJAX requests as you answer and send
email. As I type this message all of the AJAX requests on the screen are
sent via HTTP POST even though the page has not reloaded. This is standard
HTTP traffic for an AJAX application.

Anyway, I think this discussion is taking us off track of this bug. If
you'd like to know more about AJAX I'd be happy to answer your questions on
G+, http://gplus.to/markbennett.

[DartBot]

This comment was originally written by @seaneagan

---

Right, POSTs are not declining, but the Content-Type of POSTs is moving towards standard data interchange formats such as "application/json" and away from "application/x-www-form-urlencoded". Thus, code would look more like:

final in = new StringInputStream(request.inputStream));
in.onClosed(() => foo(JSON.parse(in.read())))

as opposed to:

foo(request.form);

[DartBot]

This comment was originally written by @MarkBennett

---

Hmm, submitting the content as JSON is actually something I haven't seen much of as most of the APIs I've written / used still tend to use multipart form encoding for posts.

I could see the advantages of submitting JSON in the request as serializing complex objects as form parameters isn't well defined. What API's are using this technique though?

PS - thanks for the code example, it made what you're saying much clearer. :)

[DartBot]

This comment was originally written by ladicek@gmail.com

---

submitting HTML forms is being replaced by ajax and other methods which do not cause a page reload

Sometimes, but not really always. We need to support both equally well -- let's keep in mind that Dart (not only the language, but also the libraries!) should work well for small and large projects, and moving logic to the client side isn't always the best option.

My personal opinion: we should separate access to query params and form params. Having HttpRequest.params isn't very descriptive, I'd say that it would only make sense for combined query+form params. But renaming "queryParameters" to "queryParams" would be totally OK, even to "query" (it isn't ambiguous). Form params could be accessed by "formParams", but I'm not exactly sure about "form" (but what the heck, it isn't that ambiguous).

[sgjesse]

Having the query string as a Uri seems like a good sugestion. As this will be a breaking change setting this as milestone 1.

Handling of FROM POST should be added as well. This part is moved to issue http://code.google.com/p/dart/issues/detail?id=3439.

---

Added this to the M1 milestone.

[madsager]

Removed this from the M1 milestone.

[sgjesse]

Added this to the M5 milestone.

[sgjesse]

Proposed change in https://codereview.chromium.org/15688013/.

This removes the queryParameters getter as the parsed queryParameters are now available from the Uri object.

[sgjesse]

queryParameters getter removed from HttpRequest in https://code.google.com/p/dart/source/detail?r=23413.

---

Added Fixed label.

[kevmoo]

Removed Area-IO label.
Added Area-Library, Library-IO labels.