HTTP Client

The HTTP client class is used to maintain a connection to an HTTP service. In Casablanca, we organized the API such that you first create an instance of http_client, which represents a connection to the server; using the client instance, you then send requests to the server.

To create a client instance, you need a URI representing the protocol, the host, and optionally the port number (there are protocol-specific default port numbers). The client constructor accepts either a string or a URI:

web::http::client::http_client client(U("http://localhost:1234"));

Once you have your client, making requests is as straight-forward as determining the relative URI that the request should use, i.e. the path, query and fragment, and deciding on what HTTP method to use. The method is usually one of GET, PUT, POST or DELETE. The service your code is contacting will specify what method to use when. For example, browsers use GET to retrieve content from web servers.

client.request(web::http::methods::GET, U("index.html"));

This is all well and good, but how do you get the result? Well, the request() method returns a task<http_response>, which will provide the response object once the headers have arrived. To get the http_response object and avoid blocking the current thread and use .then() :

client.request(web::http::methods::GET, U("/foo.html")).then([=](pplx::task<web::http::http_response> task)
{
    web::http::http_response response = task.get();
    ...
});
If your response contains body data as well it can be retrieved using a variety of methods on the http_response class: extract_string(), extract_vector(), extract_json(), or body() to get the underlying stream of the body.

Take a look at our BingRequest sample for a simple example.

Last edited Mar 10, 2014 at 9:12 PM by roschuma, version 13