Sound advice

Tales from the homeworld

My current feeds

Mon, 2008-Jun-30

GET

Intent

Acquire server application state in a known form

Motivation

Client C wants to acquire recent state from server S for processing.

Applicability

GET is appropriate when the client knows when it should acquire state, and when it has or can construct a URL with which to issue a GET request.

Structure

GET pattern structure

Participants

Client

The component that wants to acquire data for processing. This component knows the URL of the data. It has been written with the current version of the Registry in mind, and is capable of parsing all forms that the data might be encoded in that are semantically rich enough to use.

Server

The component that has or can produce a document containing the data Client wants. Server has been written with the current version of the Registry in mind, and is capable of encoding its information into any form that the data can legally be encoded into.

Collaboration

Client issues a GET request to Server. Included in this request is a target URL, a condition, and a weighted list of document types that Client supports. Server interprets the URL to determine which of its information sets it should return. Condition is evaluated to short-circuit processing if not required. The weighted list of document types is used to match against the set Server can return. Processing occurs, and the result is send back to Client.

A document, matched document type, and cache control information are returned with the response. Client uses the matched document type to select the right parser implementation to use in order to extract useful information from the document. Cache control information is retained to use in the next request.

A failure response may be returned, in which case the client should not attempt to retry the request. Alternatively a resubmit response may be returned. This indicates zero or more changes to the request that must be made before it can be resubmitted. Changes may include modifications to the request URL (redirection), modification to the time the request must be submitted (service unavailable), or may be a generic resubmit request that requires no changes.

On receiving a resubmit response, the client makes any identified changes and reattempt its request. If it is unable to make the identified changes due to implementation or policy limitations the client treats the response as failed.

Loss of a response due to timeout or connection failure is equivalent to a resubmit response with no identified changes required. It is always safe to repeat a GET request. 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 were constructed.

Consequences

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 in security-sensitive environments.

Implementation

Sample Code

request request;
request.url="http://example.com/publication-dates"
request.accept=parser.accept
request.condition=cache_manager.condition(url)
try_again:
switch (get(url, , accept))
{
Success(document, type, cache):
	cache_manager.update(document, type, cache)
	process(parser(document, type))

Condition Fail():
	// 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

Related Patterns

Mon, 2008-Jun-30

Registry

Intent

Support serendipitous reuse across an architecture

Motivation

Producer P and consumer C want to transfer a document. P has a particular abstract data schema in mind, and C has a compatible schema. Registry ensures that P encodes and transmits the information in a form that C understands.

Applicability

Registry is applicable for REST architectures large and small. However, the borderlines between architectures can be blurry. A satellite architecture within a particular enterprise may contain a Registry that refers to the registries of the Web. The satellite architecture may extend or jargonise the Web's registries. The borderlines between the main Web an its satellites may change over time, and components of a satellite registry may eventually form part of the main registry.

Architectures with only a small number of components may not need a formal registry.

Structure

A registry consists of:

  • A list of document types
  • A list of protocol interactions
  • Specification Documents
  • A Change management process to control the list over time

Participants

Collaboration

Consequences

Implementation

Sample Code

Known Uses

The IETF defines a registry and change management process that includes a list of protocol interactions for document transfer (HTTP/1.1) and legal document types (the IANA).

Related Patterns