REST API

This section will discuss the GeoWebCache REST API.

Formats and representations

A format specifies how a resource should be represented. A format is used:

  • In an operation to specify what representation should be returned to the client

  • In a POST or PUT operation to specify the representation being sent to the server

In a GET operation the format can be specified in a number of ways. The first is with the Accepts header. For instance setting the header to “text/xml” would specify the desire to have the resource returned as XML. The second method of specifying the format is via file extension. For example consider the resource “foo”. To request a representation of foo as XML the request uri would end with “foo.xml”. To request as JSON the request uri would end with “foo.json”. When no format is specified the server will use its own internal format, usually html.

In a POST or PUT operation the format specifies 1) the representatin of the content being sent to the server, and 2) the representation of the resposne to be sent back. The former is specified with the Content-type header. To send a representation in XML, the content type “text/xml” or “application/xml” would be used. The latter is specified with the Accepts header as specified in the above paragraph describing a GET operation.

The following table defines the Content-type values for each format:

Format

Content-type

XML

text/xml

JSON

application/json

HTML

application/html

Authentication

POST, PUT, and DELETE requests (requests that modify resources) require the client to be authenticated. Currently the only supported method of authentication is Basic authentication.

Status codes

A Http request uses a status code to relay the outcome of the request to the client. Different status codes are used for various purposes through out this document. These codes are described in detail by the http specification.

Previous: Special HTTP Response Headers
Next: Managing Global Server Configuration through the REST API