Requests

The output below is an example of the Headers sent as part of the request. As you can see, the request specifies the format and encoding it expects to receive from the response. It also specifically mentions the host and path where the requestor believes the resource is located.

GET /Protocols/rfc2616/rfc2616.txt HTTP/1.1
User-Agent: HTTPie/0.9.2
Host: www.w3.org
Connection: keep-alive
Accept: */*
Accept-Encoding: gzip, deflate

The response shown below will indicate whether a resource was found on the host and path indicated in the request and will include some additional information about the response. The status code offers a quick, specific update on whether or not the request was successful. It also indicates the format of the response, the length of the response, and some cache information like the last time the page was edited, the date and time of the request, and a date and time for when the results of this request expire.

HTTP/1.1 200 OK
Date: Fri, 18 Dec 2015 04:15:45 GMT
Server: Apache/2
Last-Modified: Tue, 29 Jul 2008 15:34:19 GMT
ETag: "69810-4532b5f92d4c0"
Accept-Ranges: bytes
Content-Length: 432144
Cache-Control: max-age=21600
Expires: Fri, 18 Dec 2015 10:15:45 GMT
P3P: policyref="http://www.w3.org/2014/08/p3p.xml"
Content-Type: text/plain

In the examples above, it’s important to note the headers are sent in plain-text and each header is terminated by a carriage return and new line character ( ). It is possible to inspect these headers in Chrome and Firefox by right clicking on the page and selecting Inspect Element. This will open up the browsers development tools. Once the window opens on the bottom, the Network tab will allow you to see all the HTTP requests that were made to render the page. Clicking on any single request will reveal information about the request, including the Request and Response headers. You can also download browser extensions to directly craft and inspect HTTP requests.

Requests are messages sent from the client to the server and give the server enough information to carry out an action on the supplied resource. The resource is identified by a URI, or Uniform Resource Indicator. A URI has a couple of components: the protocol, the host, and the path. A URL, or Uniform Resource Locator, is a type of URI and has the following format:

{protocol}://{host}{path}{query:optional}{port:optional}

You’ll notice there are place holders for query and port, both of those components aren’t required to form a valid URI. A default port for the specified protocol will be used if it is missing, for HTTP it is port 80. Query is completely optional. The client must provide the server with the resource, the data for the resource, and the action the server should attempt. There are many tools we use everyday that will abstract this step away, for example, a web browser. With a web browser, we provide the resource we’d like the server to retrieve and display for us. We don’t necessarily need to know we’re asking the server to perform a GET action on the resource, but that’s exactly what happens.

While providing the action and resource isn’t overly complicated, it makes sense to take a quick look at how this is formatted.

GET http://facebook.com HTTP/1.1

By looking at this request, one can readily determine what the client is asking the server to do. We’re sending a request to http://facebook.com and asking the server to get or retrieve the resource located at http://facebook.com. If you notice, the HTTP version is also being sent along with the action and the resource. This is explicitly telling the server what version of HTTP to use. Finally, each header in the request is terminated by a CRLF (carriage return line feed). A later section in this chapter will delve into more specific information about the actions a server can understand and how those actions operate.

While the header above will make the request to facebook.com and retrieve the resource, there are other headers that can be sent to protect us, and ensure we only get back the type of resources we expect. Some of these are very important, especially when dealing with unfamiliar APIs, but it’s usually a good practice to include them in any case. I have provided more information on some of these useful headers in the next section.

GET http://somecoolapi.com/v1/user/1b1c3fe76a HTTP/1.1
Accept: application/json

GET http://somecoolapi.com/v1/user/1b1c3fe76a HTTP/1.1
Accept-charset: utf-8

GET /v1/user/1b1c3fe76a HTTP/1.1
Host: http://example.com

Response

Once the server receives the request, it attempts to fulfill the request and responds to the client with the results of the request. In the same way that the headers are descriptive of the request, the response sends headers describing the results of the request. As you might expect, a successful request indicates the server was able to locate the resource and perform the specified action on the resource. A request can fail for a number of reasons; it’s possible the resource couldn’t be found, the request wasn’t formatted properly, or the client doesn’t have permission to access the resource. Every request has a status code corresponding to result of the request; they are universally used and understood.

The response gives the client the opportunity to respond to the failure in an appropriate way. For example, in the web browser a request to a missing resource could generate a 404 page. When making a request to a web service it can be used to craft a message in a web environment, throw an Exception, or create a log entry for the errant request. To gain an understanding of how to analyze the HTTP response we’ll look at a few common, meaningful headers as well as how to set server specific headers.

200 OK

Content-Type: application/json

Content-Length: 9720

X-Rate-Limit-Limit: 150
X-Rate-Limit-Remaining: 130

Stateless Nature of HTTP

HTTP is stateless, which means every single request is independent of any other requests. Once a login request is processed, HTTP no longer knows anything about the request. It has no idea if the previous request was successful, if a new request is from the same user, or even if the user was logged in. This, of course, requires any state maintenance to be handled by the developer outside of HTTP. To handle this developers often use cookies, sessions, databases, or caching tools. The state retrieved from those tools would need to be explicitly sent with each HTTP request or the application would have to prevent the request from being made if the user is in the incorrect state.

When a user logs into a web application, an HTTP request is made to a resource to ensure the provided credentials match a user in the system. From that point onward the application “remembers” the user is logged in. Imagine if the user had to login to an email system and then re-enter their credentials before opening every email; it would be hard to imagine that email service (or any other service) convincing people to use their site. It’s a pretty ridiculous scenario, right? This is exactly what HTTP requires.

By State we mean an application remembers some details about a client from one request to the next.

The concept is really quite straight-forward, HTTP operates independently of your application or DSL (Domain Specific Language) and won’t understand what “logged in” or “authorized” means in the context of the application. Understanding this also helps you develop intelligently and securely; by trying to make HTTP do something it’s not meant to do, we can put our users’ data at risk.

Verbs and Statuses

If you read the previous section, you read some references to “actions” or HTTP verbs and statuses. Verbs are used by the client to communicate what action the server should take on the resource. Statuses are codes that correspond to phrases to communicate whether or not the request was successful. There are number of statuses which provide a detailed explanation of what happened with the request. These two concepts are very important in understanding how to interact with web services.