Sound advice

Tales from the homeworld

My current feeds

Tue, 2008-Jul-01

GET

Intent

Transfer a defined set of information from its owner to an anonymous client in a form the client understands.

Motivation

Servers often wish to expose information for general client consumption exposing the method by which that information is produced, without having to keep track of the clients, and without introducing unnecessary coupling with the client.

The server wants to be able to support clients of different ages, some of whom will share the latest an greatest understanding of how to encode and parse particular kinds of data. Others will be left with legacy implementations. Likewise, the server may have been deployed for some time and may be running a legacy implementation while upgraded clients are present in the architecture.

Clients do not wish to create unnecessary load on the server, so look for ways in which they can minimise both traffic and processing. Clients also need to be able to deal with possible error conditions, including communication failures.

The GET pattern provides a clean client/server separation that is able to survive independent upgrades of each over time, control over traffic and processing waste, and deals with possible errors.

Applicability

GET is appropriate whenever a client wants to acquire the whole of the information behind a known URL, and can decide when it wants to issue the request (subject to a cache miss). Here are some common means by which a URL is discovered:

  1. Direct entry allows a user to enter the URL through an input device
  2. Configuration allows a document to be prepared ahead of time with links that have particular meaning to the client
  3. Hyperlinking is a generalisation of configuration. The document that contains meaningful links may be acquired from anywhere, including an earlier completed GET request
  4. Construction is the assembly of information available to the client into a URL format agreed with the server. This may be achieved by populating a form supplied by the server in an earlier GET request.

Methods of determining when to issue a GET request include:

  1. One-shot, the issuing of a request at a predefined time, when the URL first becomes known, or when the client needs access to the data
  2. Cyclic, the issuing of a request at a predefined rate while the client is active
  3. On cache expiry, the issuing of a request whenever a cache entry expires. Note that this requires the server to set a maximum age on cache entries, something that is not always provided.
  4. Otherwise-triggered, the issuing of a request based on some form of back-channel that indicates information at a given URL may have changed

Structure

GET pattern structure

Participants

Client
  • Keeps a URL that lets it access the Server
  • Issues the GET request
  • Is capable of parsing all forms that the data might be encoded in that are semantically rich enough to use
  • Selects the right parser implementation to use based on the returned document type
  • (optional) Retains a cache of past successful GET responses and their related cache control information
  • Is responsible for overall successful execution of the operation, including modifications to the request and resubmissions of the request
  • Treats a lost response as equivalent to a Resubmit response with no required changes
  • Aborts the operation on a failure response, on a resubmission response that cannot or will not be satisfied, or on a lost response after too many retries.
Server
  • Evaluates any provided condition before performing significant processing
  • Selects the information to return based on the supplied URL
  • (optional) Is configured with mechanism to require the client to resubmit their request with or without modifications
  • Guarantees that the GET request is safe initially (is not interpreted as a request to modify state), and safe to repeat.
  • Is capable of encoding its information in any form that the data can legally and reasonably be encoded to.
  • Selects the most appropriate encoding based on the supplied weighted acceptable types list and any preference it may have itself, and returns the document in that format

Collaboration

  • Client issues requests to Server via the Request Interface, modifying and resubmitting its request as needed until:
    1. A success response is elicited
    2. The request condition is not met, meaning that the cached response is still valid
    3. A failure response is elicited
    4. The client is unable to make changes required by a Resubmit response
    5. Client policy prevents either changes required by a Resubmit response, or further resubmissions in general

Consequences

The GET pattern introduces a Uniform Interface for transferring identified sets of information from server to client. Clients and servers of different ages can communicate without impediment, and communication failures can be overcome.

The use of an acceptable types list in a GET request means that clients built during different phases of the architecture will generally be able to communicate. Document-based communication has a degree of flexibility built in with must-ignore parameters. The acceptable types list fills a gap when incompatible changes occur to the set of document types, for example a new type deprecates an old type such as atom depreciating rss for news feed syndication.

An explicit failure response allows problems in the architecture to be reported and repaired as required. The resubmit feature allows temporary or permanent changes to the architecture to be accommodated by components without explicit reconfiguration, simplifying management. Note, however, the potential security implications of allowing one component to reconfigure others. A predefined policy for which modifications are permitted and which are to be treated as failure cases can be useful in security-sensitive environments.

Note that it may be necessary to avoid allowing multiple GET requests to be outstanding simultaneously to the same or related URLs. The potential exists in common transports such as HTTP for simultaneous or pipelined requests to be processed in a different order to that in which they actually return to Client.

Implementation

GET can be implemented with HTTP using the following mappings:

GET(url, condition, weighted acceptable types list)

becomes

GET url HTTP/1.1
Accept: weighted acceptable types list
If-condition
Success(document, type, cache)

becomes

HTTP/1.1 200 OK
Content-Type: type
Cache-Control: cache

document

All 2xx series response codes can be treated as Success responses for GET

Condition Not Met()

becomes

HTTP/1.1 304 Not Modified
Fail(reason)

becomes

HTTP/1.1 400 Bad Request

reason

Unknown 1xx series response codes can be treated as a Fail for GET. 300 Multiple Choices is a non-implementable Resubmit response for automated clients, so should also be treated as Fail alongside other 3xx series codes that are not understood. 4xx series response codes are Fail, except for 401 Unauthorised and 407 Proxy Authentication Required. These are Resubmit responses and should only be treated as failures if they are not understood. 5xx series responses should be treated as Fail, except for 503 Service Unavailable and 504 Gateway Timeout. These are Resubmit and Response Lost responses, respectively.

Resubmit(required changes)

becomes any of:

301 Moved Permanently, 302 Found, 303 See Other, 305 Use Proxy, 307 Temporary Redirect, 401 Unauthorized, or 407 Proxy Authentication Required.

Response Lost()

becomes any loss of communication before a response is received. This may include application or TCP/IP level timeouts, or an explicitly terminated connection. The 504 Gateway Timeout response is also equivalent to Response Lost, and indicates a loss occured somewhere past the TCP connection made directly by the client.

Sample Code

Request request;
request.url="http://example.com/publication-dates"
if cache_manager.fresh(request.url)
{
	// Do nothing. Our cache entry is still fresh.
}
else
{
try_again:
	request.accept=parser.accept
	request.condition=cache_manager.condition(request.url)

	switch (request())
	{
	Success(document, type, cache):
		cache_manager.update(document, type, cache)
		process(parser(document, type))

	Condition Not Met():
		// Do nothing.
		// We have already processed the
		// latest data with our last request.

	Fail(reason):
		log(reason)

	Resubmit(required_changes):
		if policy(request, required_changes)
			request.modify(required_changes)
			jump try_again;
		else
			log("Policy forbids request modification");

	Response Lost():
		if policy(request, no required changes)
			jump try_again;
		else
			log("Too many retries");
	}
}

Known Uses

GET is widely used on the Web, both under direct human control and under automation. Various aspects of GET are not always used well.

Related Patterns