.. _mapcache_http:

*****************************************************************************
HTTP Requests
*****************************************************************************


HTTP configuration blocks are used in multiple places in the MapCache configuration.

Specifying the URL
------------------

The simplest HTTP configuration block requires a single `<url>` child element:

.. code-block:: xml

  <http>
    <url>http://server/path?key=value</url>
  </http>

Timeouts
--------

You may configure the timeouts after which an HTTP request is abandoned:

.. code-block:: xml

  <http>
    <url>http://server/path?key=value</url>

    <!-- timeout in seconds to wait while establishing a connection. This may be needed for
    firewalled MapCache or HTTP instances -->
    <connection_timeout>30</connection_timeout>

    <!-- total maximum time allowed for the whole request. Includes the time needed to
   transfer data down the wire -->
    <timeout>60</timeout>
  </http>

Headers
-------

You can insert custom headers in the request, or forward headers received from the client
request:

.. code-block:: xml

  <http>
    <url>http://server/path?key=value</url>
    <headers>
      <User-Agent>My MapCache User-Agent</User-Agent>   <!-- hard coded header -->
      <X-My-Forwarded-Header>{X-Received-Header}<X-My-Forwarded-Header> <!-- Forwarded from client, optionally changing the header name -->
      <X-My-Forwarded-Header-2>foobar-{X-Received-Header}-baz<X-My-Forwarded-Header-2> <!-- Forwarded and modified from client, optionally changing the header name -->
    </headers>
  </http>

