WCS RESTful Protocol Binding

This WCS extension specifies how Web Coverage Service (WCS) clients and servers can communicate over the Internet using a RESTful interface over HTTP. The RESTful binding is provided in addition to the GET/KVP, POST/XML, and SOAP; all protocol bindings materialize the same underlying semantics. -- PeterBaumann - 07 May 2013

Approach: REST favors hierarchical structuring of information offerings, and this fits perfectly with coverage data and services:

• At the top level, a server offers a set of coverages. This allows to provide access on the service level, and to drill down to individual coverages. But it also allows to access service level information, such as formats and extensions supported.
• A coverage, being aka digital representation of a space-time varying phenomenon, consists of a set of items (often aligned on a grid), called pixels, voxels, cells, etc. A RESTful interface allows drilling down into a coverage, i.e. a cell set, by way of functions such as subsetting, but also more complex ways like scaling or CRS transforms.

Hence, the approach is adopted in the WCS REST Binding Extension specification [OGC 12-174] that WCS functionality facets in the RESTful binding are provided as path components, possibly parametrized. This allows to avoid query parts in a URL, thereby achieving a "pure" REST style. Further, this service model is completely in line with the UML service description provided with WCS Core [OGC 09-110r4].

Status: The specification draft, OGC 12-174 has been discussed by the WCS.SWG favorably. A few discussion items need to be resolved before, by way of motion, a public Request for Comment (RFC) will be launched. Hence, information presented on this page is not an OGC standard yet.

Background on REST: Unfortunately, there is still no authoritative definition of REST. For some pertinent resources, see, eg, http://en.wikipedia.org/wiki/Representational_state_transfer and http://tech.groups.yahoo.com/group/rest-discuss/messages/1?l=1 .

Capabilities

Support of this extension is indicated in the Capabilities document of a server by presence of the Profile element http://www.opengis.net/spec/WCS_protocol-binding_rest/1.0/conf/rest. This is the mechanism used for all extensions.

To request a capabilities document a client can request the service resource by issuing an HTTP GET request to an URL of this form: {service}/capabilities.

Example:

http://www.acme.com/WCS/capabilities

Coverage Retrieval

Retrieving a complete coverage is requested by adding the keyword "coverage" followed by the coverage identifier to the service path: {service}/coverage/{coverage-id}.

Example: http://hostname:port/contextPath/WCS/2.0/coverage/C0001

Retrieving a subset of a coverage is requested by adding path components for each axis where subsetting is done, in any order (ie, not tied to axis sequence in the coverage's CRS). Subsetting syntax is functional, with a function name of "subset()". For a trim operation, lower and upper bound are indicated, for a slice operation only the slice point.

Example: Trimming in lat and long plus slicing in time can be expressed as:

http://www.acme.com/WCS/coverage/C0001/
    subset(lon(-71:47))/
    subset(lat(-66:51))/
    subset(t("2009-11-06T23:20:52Z"))

Coverage Encoding

A client may indicate encoding preferences for the coverages retrieved. If no preference is indicated, the coverage is delviered in its Native Format as stored on the server.

Encoding preferences are indicated in the Accept Header of the HTTP GetCoverage request, in accordance with RFC 2616 Clause 14 - by way of examples:

Example 1: The following request header indicates that a representation of the coverage resource addressed in the path is to be delivered by the server in JPEG2000 format:

Accept: image/jp2

Example 2: The following request header indicates that one of JPEG2000 and PNG is acceptable, and the server can pick one response format at its discretion:

Accept: image/jp2, image/png

Example 3: The following request header indicates that the client prefers to receive TIFF, but any image format is acceptable if it is the best available after an 80% mark-down in quality:

Accept: image/*; q=0.2, image/tiff; 

Example 4: The following request header indicates that the client prefers to receive JPEG2000, with a GML metadata header, both combined into a multipart/related message as defined in GMLCOV:

Accept: image/jp2; mediaType=multipart/related

All these mechanisms can be combined freely as long as they are coherent with RFC 2616.

Coverage Description

A DescribeCoverage request delivers metadata about a coverage (i.e., all constituents except for the "pixel" payload). This representation of the coverage metadata part is requested by suffixing the coverage selected with a description path element: <tt>{service}/{coverage-id}/description</tt>.

Example: To request the description resource of a coverage resource a client can request it by issuing an HTTP GET request to an URL of this form:

http://www.acme.com/WCS/coverage/C0001/description

Extensions

The above operations are established for the WCS Core; WCS extensions may add particular request parameters which, in RESTful syntax, translate into additional path components.