HTTP Client API — cpp-netlib v0.13.0

# HTTP Client API

## General

`cpp-netlib` includes and implements a number of HTTP clients that you can use and embed in your own applications. All of the HTTP client implementations:

> - Cannot be copied. This means you may have to store instances of the clients in dynamic memory if you intend to use them as function parameters or pass them around in smart pointers or by reference.
> - Assume that requests made are independent of each other. There currently is no cookie or session management system built-in to cpp-netlib’s HTTP client implementations.

The HTTP clients all share the same API, but the internals are documented in terms of what is different and what to expect with the different implementations.

## Features

The HTTP client implementation supports requesting secure HTTP (HTTPS) content only in the following situations:

> - Client libraries are built with ``BOOST_NETWORK_ENABLE_HTTPS``. This tells the implementation to use HTTPS-specific code to handle HTTPS-based content when making connections associated with HTTPS URI’s. This requires a dependency on OpenSSL.
> - The ``BOOST_NETWORK_ENABLE_HTTPS`` macro is set when compiling user code. It is best to define this either at compile-time of all code using the library, or before including any of the client headers.

To use the client implementations that support HTTPS URIs, you may explicitly do the following:

    #define BOOST_NETWORK_ENABLE_HTTPS
    #include <boost/network/include/http/client.hpp>

This forces HTTPS support to be enabled and forces a dependency on OpenSSL. This dependency is imposed by Boost.Asio

## Client Implementation

There is a single user-facing template class named `basic_client` which takes three template parameters:

> - Tag - which static tag you choose that defines the behavior of the client.
> - http_version_major - an unsigned int that defines the HTTP major version number, this directly affects the HTTP messages sent by the client.
> - http_version_minor - an unsigned int that defines the HTTP minor version number.

In the above table the tags follow a pattern for describing the behavior introduced by the tags. This pattern is shown below:

> <protocol>_<modifier>_<character-width>_<resolve-strategy>

For example, the tag `http_default_8bit_tcp_resolve` indicates the protocol `http`, a modifier `default`, a character width of `8bit`, and a resolve strategy of `tcp_resolve`.

The client is implemented as an Active Object. This means that the client has and manages its own lifetime thread, and returns values that are asynchronously filled in. The response object encapsulates futures which get filled in once the values are available.

Note

The client objects are thread safe, and can be shared across many threads. Each request starts a sequence of asynchronous operations dedicated to that request. The client does not re-cycle connections and uses a one-request-one-connection model.

When a client object is destroyed, it waits for all pending asynchronous operations to finish. Errors encountered during operations on retrieving data from the response objects cause exceptions to be thrown – therefore it is best that if a client object is constructed, it should outlive the response object or be outside the try-catch block handling the errors from operations on responses. In code, usage should look like the following:

    http::client client;
    try {
      http::client::response response = client.get("http://www.example.com/");
      std::cout << body(response);
    } catch (std::exception& e) {
      // deal with exceptions here
    }

A common mistake is to declare the client inside the try block which invokes undefined behavior when errors arise from the handling of response objects. Previous examples cited by the documentation showed the short version of the code which didn’t bother moving the `http::client` object outside of the same `try` block where the request/response objects are being used.

## Member Functions

In this section we assume that the following typedef is in effect:

    typedef boost::network::http::basic_client<
        boost::network::http::tags::http_default_8bit_udp_resolve
        , 1
        , 1
        >
        client;

Also, that code using the HTTP client will have use the following header:

    #include <boost/network/include/http/client.hpp>

### Constructors

The client implementation can be default constructed, or customized at initialization.

`client()`
  Default constructor.
`explicit client(client::options const &)`
  Constructor taking a `client_options<Tag>` object. The following table shows the options you can set on a `client_options<Tag>` instance.

### Client Options

template <class Tag>
class `boost::network::http::``client_options`

  Public Functions

  `client_options`()

    Set all the options to default.

  client_options &`cache_resolved`(bool v)

    Specify whether the client should cache resolved endpoints.

    Default: false.

  client_options &`follow_redirects`(bool v)

    Specify whether the client should follow redirects.

    Default: false.

  client_options &`openssl_certificate`(string_type const &v)

    Set the filename of the certificate to load for the SSL connection for verification.

  client_options &`openssl_verify_path`(string_type const &v)

    Set the directory for which the certificate authority files are located.

  client_options &`openssl_certificate_file`(string_type const &v)

    Set the filename of the certificate to use for client-side SSL session establishment.

  client_options &`openssl_private_key_file`(string_type const &v)

    Set the filename of the private key to use for client-side SSL session establishment.

  client_options &`openssl_ciphers`(string_type const &v)

    Set the ciphers to support for SSL negotiation.

  client_options &`openssl_sni_hostname`(string_type const &v)

    Set the hostname for SSL SNI hostname support.

  client_options &`openssl_options`(long o)

    Set the raw OpenSSL options to use for HTTPS requests.

  client_options &`io_service`(std::shared_ptr<boost::asio::io_service> v)

    Provide an `boost::asio::io_service` hosted in a shared pointer.

  client_options &`always_verify_peer`(bool v)

    Set whether we always verify the peer on the other side of the HTTPS connection.

    Default: true.

  client_options &`timeout`(int v)

    Set an overall timeout for HTTP requests.

To use the above supported named parameters, you’ll have code that looks like the following:

    using namespace boost::network::http; // parameters are in this namespace
    client::options options;
    options.follow_redirects(true)
           .cache_resolved(true)
           .io_service(boost::make_shared<boost::asio::io_service>())
           .openssl_certificate("/tmp/my-cert")
           .openssl_verify_path("/tmp/ca-certs")
           .timeout(10);
    client client_(options);
    // use client_ as normal from here on out.

### HTTP Methods

The client implementation supports various HTTP methods. The following constructs assume that a client has been properly constructed named `client_` and that there is an appropriately constructed request object named `request_` and that there is an appropriately constructed response object named `response_` like the following:

    using namespace boost::network::http;  // parameters are here
    client client_();
    client::request request_("http://cpp-netib.github.com/");
    client::response response_;

template <class Tag, unsigned version_major, unsigned version_minor>
class `boost::network::http::``basic_client`

  Basic Client API.

  This template defines an HTTP client object that is non-copyable and is implemented depending on the `Tag` parameter. It also hard-codes the version of HTTP to support.

  Template Parameters
    - `Tag`: The Tag type used to determine certain traits of the implementation. We use the Tag as an input to other template metafunctions to determine things like the string type, whether to use TCP or UDP for the resolver, etc.
    - `version_major`: The HTTP major version.
    - `version_minor`: The HTTP minor version.

  Inherits from boost::network::http::basic_client_facade< Tag, version_major, version_minor >

  Public Types

  typedef Tag `tag_type`
  typedef client_options<Tag> `options`
  typedef string<Tag>::type `string_type`

    The type to use for strings associated with this client. Typically resolves to `std::string`.

  typedef basic_request<Tag> `request`

    The request type. This models the HTTP Request concept.

  typedef basic_response<Tag> `response`

    The response type. This models the HTTP Response concept.

  typedef std::array<typename char_<Tag>::type, 1024>::const_iterator `const_iterator`
  typedef iterator_range<const_iterator> `char_const_range`
  typedef std::function<void(char_const_range, boost::system::error_code const&)> `body_callback_function_type`

    This callback is invoked with a range representing part of the response’s body as it comes in. In case of errors, the second argument is an error code.

  typedef std::function<bool(string_type&)> `body_generator_function_type`

    Functions that model this signature will be used to generate part of the body while the request is being performed. This allows users to provide a generator function that will generate the body of the request piece-wise.

    Implementations should return `true` if there is more to the body of the request, and `false` otherwise.

  Public Functions

  `basic_client`(options const &options)

    This constructor takes a single options argument of type client_options. See boost/network/protocol/http/client/options.hpp for more details.

  `basic_client`()

    This default constructor sets up the default options.

  response `head`(request const &request)

    Perform a HEAD request.

  response `get`(request const &request, body_callback_function_type body_handler = body_callback_function_type ())

    Perform a GET request.

    Return
      A response object.
    Parameters
      - `request`: The request object including the URI and headers.
      - `body_handler`: If provided, a callback invoked for parts of the response’s body.
    Exceptions
      - `std::exception`: May throw exceptions on errors, derived from `std::exception`.
  response `post`(request request, string_type const &body = string_type (), string_type const &content_type = string_type (), body_callback_function_type body_handler = body_callback_function_type (), body_generator_function_type body_generator = body_generator_function_type ())

    Perform a POST request.

    Return
      A response object.
    Parameters
      - `request`: A copy of the request object including the URI and headers.
      - `body`: The whole contents of the body. If provided, this overrides the body in the `request`.
      - `content_type`: The content type for the request. This overrides the content type in the `request`.
      - `body_handler`: The callback invoked for parts of the response body as they come in.
      - `body_generator`: If provided, is invoked to generate parts of the request’s body as it is being sent.
    Exceptions
      - `std::exception`: May throw exceptions on errors, derived from `std::exception`.
  response `post`(request const &request, body_generator_function_type body_generator, body_callback_function_type body_handler = body_callback_function_type ())

    Perform a POST request.

    Return
      A response object.
    Parameters
      - `request`: The request including the URI and headers.
      - `body_generator`: The function to call to generate part of the body while the request is being performed.
      - `callback`: If provided, the function to call for parts of the response’s body as they come in.
    Exceptions
      - `std::exception`: May throw exceptions derived from std::exception in case of errors.
  response `post`(request const &request, body_callback_function_type body_handler, body_generator_function_type body_generator = body_generator_function_type ())

    Perform a POST request.

    Return
      A response object.
    Parameters
      - `request`: The request including the URI and headers.
      - `body_generator`: The function to call to generate part of the body while the request is being performed.
      - `callback`: If provided, the function to call for parts of the response’s body as they come in.
    Exceptions
      - `std::exception`: May throw exceptions derived from std::exception in case of errors.
  response `post`(request const &request, string_type const &body, body_callback_function_type body_handler, body_generator_function_type body_generator = body_generator_function_type ())

    Perform a POST request.

    Return
      A response object.
    Parameters
      - `request`: The request object including the URI and headers.
      - `body`: The whole contents of the body.
      - `body_handler`: The callback invoked for parts of the response body as they come in.
      - `body_generator`: If provided, is invoked to generate parts of the request’s body as it is being sent.
    Exceptions
      - `std::exception`: May throw exceptions on errors, derived from `std::exception`.
  response `put`(request request, string_type const &body = string_type (), string_type const &content_type = string_type (), body_callback_function_type body_handler = body_callback_function_type (), body_generator_function_type body_generator = body_generator_function_type ())

    Perform a PUT request.

    Return
      A response object.
    Parameters
      - `request`: A copy of the request object including the URI and headers.
      - `body`: The whole contents of the body. If provided, this overrides the body in the `request`.
      - `content_type`: The content type for the request. This overrides the content type in the `request`.
      - `body_handler`: The callback invoked for parts of the response body as they come in.
      - `body_generator`: If provided, is invoked to generate parts of the request’s body as it is being sent.
    Exceptions
      - `std::exception`: May throw exceptions on errors, derived from `std::exception`.
  response `put`(request const &request, body_callback_function_type callback, body_generator_function_type body_generator = body_generator_function_type ())

    Perform a PUT request.

    Return
      A response object.
    Parameters
      - `request`: The request including the URI and headers.
      - `callback`: If provided, the function to call for parts of the response’s body as they come in.
      - `body_generator`: The function to call to generate part of the body while the request is being performed.
    Exceptions
      - `std::exception`: May throw exceptions derived from std::exception in case of errors.
  response `put`(request const &request, string_type body, body_callback_function_type body_handler, body_generator_function_type body_generator = {})

    Perform a POST request.

    Return
      A response object.
    Parameters
      - `request`: The request object including the URI and headers.
      - `body`: The whole contents of the body.
      - `body_handler`: The callback invoked for parts of the response body as they come in.
      - `body_generator`: If provided, is invoked to generate parts of the request’s body as it is being sent.
    Exceptions
      - `std::exception`: May throw exceptions on errors, derived from `std::exception`.
  response `delete_`(request const &request, body_callback_function_type body_handler = {})

    Perform a DELETE request.

    Return
      A response object.
    Parameters
      - `request`: The request object including the URI and the headers.
      - `body_handler`: The callback invoked for parts of the response body as they come in, if provided.
    Exceptions
      - `std::exception`: May throw exceptions on errors, derived from `std::exception`.
  void `clear_resolved_cache`()

    Clears the cache of resolved endpoints.

typedef basic_client<BOOST_NETWORK_HTTP_CLIENT_DEFAULT_TAG, 1, 1> `boost::network::http::``client`

  The default HTTP client type is an asynchronous UDP-resolving HTTP/1.1 client.

### Streaming Body Handler

As of v0.9.1 the library now offers a way to support a streaming body callback function in all HTTP requests that expect a body part (GET, PUT, POST, DELETE). A convenience macro is also provided to make callback handlers easier to write. This macro is called `BOOST_NETWORK_HTTP_BODY_CALLBACK` which allows users to write the following code to easily create functions or function objects that are compatible with the callback function requirements.

An example of how to use the macro is shown below:

    struct body_handler {
        explicit body_handler(std::string & body)
        : body(body) {}

        BOOST_NETWORK_HTTP_BODY_CALLBACK(operator(), range, error) {
            // in here, range is the Boost.Range iterator_range, and error is
            // the Boost.System error code.
            if (!error)
                body.append(boost::begin(range), boost::end(range));
        }

        std::string & body;
    };

    // somewhere else
    std::string some_string;
    response_ = client_.get(request("http://cpp-netlib.github.com/"),
                            body_handler(some_string));

You can also use if for standalone functions instead if you don’t want or need to create a function object.

    BOOST_NETWORK_HTTP_BODY_CALLBACK(print_body, range, error) {
        if (!error)
            std::cout << "Received " << boost::distance(range) << "bytes."
                      << std::endl;
        else
            std::cout << "Error: " << error << std::endl;
    }

    // somewhere else
    response_ = client_.get(request("http://cpp-netlib.github.com/"),
                            print_body);

The `BOOST_NETWORK_HTTP_BODY_CALLBACK` macro is defined in `boost/network/protocol/http/client/macros.hpp`.