HTTP Query String Parameters

Understanding Parameters

Introduction

While this discussion will focus primarily on defining what parameters are, how they’re generated and passed from the client to the server, I’ll also attempt to cover, in brief, some of the related or ancillary topics as well. I encourage those that are interested in learning more about the underlying processes to visit the links embedded throughout this post. Most of them point to either Wikipedia or to documentation provided by the various standards bodies like the Web Consortium. They likely give a more nuanced introduction to these topics and also have plenty of additional information and resources available to peruse.

In addition, I feel that it’s important to distinguish between what parameters are, independently of how they are used once received by the server. While most web frameworks or domain-specific languages, DSLs, will parse the incoming string of characters in conceptually similar ways, there will undoubtedly be some discrepancies in how the resulting data is formatted and made available for use by the developer.

So, while some examples have been included that are specific to Rails and Sinatra, in general, this post will strive to discuss parameters outside of any one specific implementation.

What are Parameters? What purpose do they serve?

It’s important to understand that, conceptually, parameters are a tool. They provide developers with a way of enabling end users to interact with a given website, be it a service or application, in a more dynamic way. That interaction might take the form of requesting specific information of, or passing data to be used and stored by the website in question.

As such, each developer decides, based on the type of service or application they are building, what the parameters are. They decide what information will be requested from the user and how that information will be used by their specific service or application. A simple search query is one example, posting a message to a blog is another.

The term parameter refers to the pieces of associated data, name | value pairs, that originate on the client, and are passed to the server. Once generated, there are two ways that parameters are transmitted from client to server, either within the query string of a URI / URL through an HTTP GET request, or as part of the body of an HTTP POST request.

How are they generated?

The definition above likely raises some additional questions.

• How are parameters actually created?
• What is meant by associated data?
• What does a parameter look like in practice?

Since parameters are data and often represent information that the developer needs the user of her website or service to provide, they are typically created using an HTML form. Every HTML form contains fields, places for users to enter data, and typically those fields are explicitly named. The relationship between the name of the field and its contents, the value of the data entered, represents the association mentioned above.

For example, this is what the HTML code for a basic form might look like. It’s here, within the input attribute that the name of each field is set.

Please Note

It’s important to distinguish between the label given to a form field and the name attribute. The label is a more general, superficial term and does not effect the relationship between the name and the value of the parameter being generated.

That said, the resulting form would look like this.

When this form is submitted, each corresponding name | value pair will be passed from the client to the server.

Each of these associated pieces of data, each name | value pair, is a parameter.

How they are sent and what they look like once received by the server, is, in part, covered below.

How are they sent? HTTP and the Request / Response Cycle

Request / Response

The Hypertext Transfer Protocol, HTTP, defines, at a high level, how a client and server communicate over a network. While there are other protocols that help facilitate this communication, such as TCP/IP, for our purpose, we’ll limit the discussion to the messages passed via HTTP through a process called request / response.

The request / response cycle begins with the client sending a request message to the server, and then waiting for the server to respond with a message of its own. Typically, the client is requesting a resource of some kind, a web page or the results of a search query. The server will then respond, delivering the various resources that were requested. The links above provide examples of what these messages look like and how the data is encoded, transmitted, and decoded at each end.

While all the information contained within each message serves an important function, the two most relevant for this discussion are the request method and the Uniform Resource Locator or URI / URL. These two pieces of information define the nature of the request and the resource that is being interacted with. When used in conjunction with HTTP, the URI / URL is often referred to as the web address.

Please Note

While outside the scope of this post, it’s important to recognize that URIs provide a standardized way for different parts of a computing device to identify one another, thus enabling them to pass messages back and forth. For more information on all the different types of URIs, check out this link.

Uniform Resource Locator, URL

The URL is the means by which users interact with a website. They determine how resources are requested and specific behavior triggered.

But what is a resource?

Often it’s a static file or web page. That’s probably the most common interpretation. But resources are actually any addressable thing or bit of data, including the result of a search or the return value of a function. The URL is the destination, the server endpoint, which, when used in conjunction with a block of code, enable the functionality of most of the web services and applications in use today. So it’s important to understand, or at least be aware, of what the individual parts of a URL represent in addition to how they work.

To begin with, URLs all share the same basic structure, which is determined by the type of resource they point to.

<scheme name> : <host or domain> / <hierarchical part> [ ? <query> ] [ # <fragment> ]

• The scheme name is often a protocol, the communication method, such as, http, ftp, ssh, mailto, or irc.
• The domain name or host is the address of the server where the individual resources reside. Such as google.com, twitter.com, or en.wikipedia.org
• The hierarchal part is appended to the host and resembles the file path often found in a Unix based OS. /file/lives/here
• The query string follows the hierarchal part and always begins with a ”?”. The data following it is grouped by an ”=” and the name | value pairs are separated by an “&”.
• The fragment follows the hierarchal part and always begins with a ”#”. It points to a specific location, often a section heading within a static file.

A URL formatted in conjunction with HTTP will include the first three components above and, possibly, a query string or fragment. Here’s an example of a web address that includes a query string.

http://superwall.com/register?name=travis&city=San+Francisco&state=California

HTTP Methods

There are a number of different request methods defined within HTTP that govern how information is passed during the request / response cycle…how messages, and the data they contain, are passed. These methods are often referred to as verbs since their names typically correspond to the action they preform. Two of the most common HTTP methods are GET and POST.

As its name implies, the GET method is used to request a specific resource. Any data associated with a GET request is represented in the URL. Typically within the hierarchal part or path. When a user makes a specific request, a search for example, the information is encoded within the query string.

The messages sent via the GET method are intended to read, not create, update, or destroy, the target resource. As such, a GET request cannot be used to alter or modify existing data on a server. This makes it the most common type of request used on the web since most activity involves asking for and receiving a specific resource, often an individual webpage.

The POST method, on the other hand, is used to create and, in conjunction with PUT and DELETE, modify or destroy existing data. While not as common as the GET method, POST is the primary way developers enable users to interact with, and persist or store data using, web applications and services.

Passing Parameters - the HTTP GET Method

Since we’ve already established what parameters are, associated pieces of data that originate on the client and passed to the server, it’s time to discuss how they get passed. There are two common ways to transmit data from the client to the server, an HTTP GET request and and HTTP POST request.

When passing data in conjunction with an HTTP GET request, the query string portion of the URL is used as the mode of transport between client and server. As mentioned above, the query string always begins with a ”?”, followed by the name | value pairs of data.

Here’s that example URL again.

http://superwall.com/register?name=travis&city=San+Francisco&state=California

The parameters being sent in this case are the three name | value pairs following the question mark, separated by an ampersand.

It’s also worth mentioning again that how this string of information is parsed and formatted once received by the server, will differ based on the framework that was used when building the web application.

In a Ruby based web framework like Rails or a DSL like Sinatra, these name | value pairs are the same as key | value pairs, a Hash, and are often referred to as the params hash.

So the resulting Hash from the URL above might look like this.

{"name"=>"travis"}, {"city"=>"san francisco"}, {"state"=>"california"}

Please Note

While outside the scope of this post, it’s important to recognize and be aware that since the primary message associated with a GET request is the URL itself, data sent in this manner is visible during the transport process. As such, it’s generally best to avoid sending anything that might be considered sensitive via a GET request and instead use a POST request.

Passing Parameters - the HTTP POST Method

Passing parameters via the HTTP POST method is similar to the HTTP GET method described above. Instead of the data being passed to the server as part of the URL, though, it’s passed within the body of the HTTP request using POST and, of course, an HTML form.

Understanding the difference, the implications of how the information is passed, is important. As touched upon in the HTTP section above, there are inherent limitations on how request methods can be used. The POST method is for creating or adding new information to a website, service, or application. It also enables, through the use of the PUT and DELETE methods, data to be updated or destroyed.

The developer decides what information will be added, the name | value pairs, when she creates the form. Here again is the HTML code for a basic POST request.

Here’s what the resulting form would look like.

The body of a POST request will look slightly different depending on the information being entered into the HTML form and, again, how that information is being used as defined within the application running on the server.

In the case of Rails or Sinatra, the name of the various fields will correspond to the key. So “title”, “description”, and “created_by” are all keys. The data entered into the form fields, “Wall of Super”, “Here I describe super things.”, and “Travis” are the values.

The resulting key | value pairs, the params Hash, might look like this when received by the server.

{"wall"=>{"title"=>"Wall of Super", "description"=>"Here I describe super things.", "created_by"=>"Travis"}}

In this example, there are actually two hashes. The first hash has a key of “wall”, the value is the second Hash we just described. Once submitted, this form would likely create a new “wall” record within the database, containing the data that corresponds to the various key | value pairs.

Please Note

As this example demonstrates, the data passed from client to server can become quite complex in nature. One of the benefits of using the HTTP POST method is that the data being transmitted is carried within the body of the request. This gives developers the freedom, or option at least, to obfuscate or hide what’s being passed between client and server.

How are they used? A Basic Example.

While largely outside the scope of this post, I wanted to provide a basic example of how parameters are often used.

Think for a moment about the Tweets you make or all the updates you post to your Facebook Timeline. All the information you enter, through a web browser, a desktop or mobile app, must be passed on to appropriate server. So the information leaves you and your client, transmitted via a form using an HTTP POST request, and ends up being received by a server running proprietary software designed by the nice folks at Twitter or Facebook.

Once it arrives, all the data is parsed and formatted as a series of key | value pairs that are then acted upon in a way defined by the developers at Twitter or FB. They undoubtedly use the information in a myriad of ways but eventually it’s inserted or added to a database and the results then displayed, in perpetuity. for all the world to see.

Or at least for your 4 followers and friends.

Summary

What parameters are, (formatted data originating on the client), how they are generated and passed on to the server, (typically via an HTML form in conjunction with an HTTP method), is key to understanding their importance and the foundational role they play within a website, service, or application. The examples above attempt to demonstrate that role and hint at what they make possible.

The implementation details, how parameters are used once they are received, parsed, and made available to the developer, is almost completely dependent on the web framework or DSL being used to create the website, service or application. Put simply, how parameters are used within Sinatra will be different than how they are used within Django. Which is why such discussions are best left for a later post.