HTTP Client overview

Purpose

The HTTP (Hypertext Transfer Protocol) Client API provides a client interface for Internet applications to use the HTTP protocol for communication with HTTP servers on the Internet. Using the API correctly enables the application to be a conditionally HTTP 1.1 compliant client, as defined in RFC 2616.

The HTTP protocol is a request and response protocol. A client sends a request to the server. This request consists of a request method, URI, and protocol version, including a Multipurpose Internet Mail Extensions (MIME)-like message containing request modifiers, client information, and body content over a server connection. The server responds with a status, which includes the message's protocol version and a success or error code, and a MIME-like message containing server information, meta information, and body content. The following image illustrates a simple HTTP session between a client and a server.

See Hypertext Transfer Protocol -- HTTP/1.1, RFC 2616 for more details.

Architectural relationships

The HTTP Client architecture provides a generalised mechanism for HTTP-like protocols that operate over various transports. Using a single API, a client can choose an HTTP protocol, encoding, and transport, and need not implement these in its own code. The default operation provides plain-text HTTP (as defined in RFC 2616) operating over a TCP/IP connection. This transport pipelines requests by default.

Description

There are five key concepts used in the API: sessions, transactions, headers, data suppliers, and filters.

Sessions

A session encapsulates the client's HTTP activity over the duration of the client's execution. Typicallly, one HTTP session runs in one active scheduler.

Note: An active scheduler must be installed when a session is opened.

Usually, one session is used at a time. However, the client may use several concurrently, if required. Each session has an associated set of properties, which define the HTTP protocol, encoding, and transport used. Those properties apply to all HTTP transactions within the life of that session. The session also has an associated set of filters that provide additional automatic behaviours on the client's behalf.

The session class is provided by RHTTPSession.

Transactions

A transaction represents an interaction between a HTTP client and an HTTP origin server. Normally a transaction consists of a single exchange of messages between client and server: a client request and a server response. However, the transaction may be extended or altered by filters that operate on it. See Filters for more details.

Transactions execute asychronously within the client's process. The client is notified when events are available for each outstanding transaction.

Both the request and response portion of a transaction consist of a header and an optional body. The request portion of the transaction also specifies an HTTP Method that describes the type of operation that the client wants to invoke at the origin server, together with a URI that specifies the resource held at the server on which the method is to be invoked. The response portion of a transaction contains an HTTP status code and message, which indicate the success of the method or the state of the resource following the method. The use of request and response bodies is determined by the HTTP method in use. For example, in error conditions, some servers may just return a status code and message, providing no entity body.

The transaction class is provided by RHTTPTransaction.

Headers

The header portion of requests and responses may have zero or more fields, which are used to convey information between the HTTP client and server. The information might relate to the data conveyed in body of the message, to the actual connection between the client and server, or might be used to convey data describing the client or server themselves. Typically, headers can contain content encoding and transfer encoding information. Since the HTTP API gives clients implementation independence from these choices, a generic form is used to represent header data in the API.

The headers class is provided by RHTTPHeaders.

Data suppliers

The body portion of requests and responses is represented in the API as a mix-in interface, allowing the real implementation of the classes that generate body data to be fully hidden. The API enables signalling between the client and the transport in use, to ensure that body data is only used or released at a rate the client can support. This means that clients can assemble the body of their requests piece-by-piece, have each piece transmitted only when it is ready, and be signalled when transmission is complete so the next piece may be prepared and the old one released.

Data supplier classes must implement MHTTPDataSupplier.

Filters

Filters are add-on modules that provide additional behaviours to a session beyond the simple request-response transaction described earlier. Behaviours may be triggered by the presence of particular headers in a request or a response, by status codes in a response, or by particular events that occur on a transaction. RFC 2616 describes a number of standard behaviours that occur over a series of request-response exchanges: client authentication, redirection, and caching. Client authentication and redirection are implemented as individual filters.

Filter classes must implement MHTTPFilter.

Refer to Filters for more information.

Example code

Example code used throughout this guide is taken from HTTPEXAMPLECLIENT, a simple console application that provides a menu-driven interface to the HTTP API.