Table of Contents
This chapter address the format and structure of queries made to a HEEP server. Most HEEP Queries are formed within and XML document using the FISHXML_Query schema, which are POSTed to a HEEP server for processing. The XML schema itself dictates the structure of the query (Section A.2, “Request Schema”, but notes are provided here for guidance. We have also provided an example FISHXML_Query within this document, and which is available for download at http://oxarchdigital.com/fish/hep/0.1/examples/example_request.xml This example is informative rather than normative, and subject to further changes and clarification..
The HEEP client shall be responsible for forming valid requests. If any element of the request is invalid, the server shall issue an exception.
HEEP server capabilities can be queried without XML using HTTP GET, where keyword/value pairs are passed through the URL. This is the only operation for which GET is supported.
Currently only the GetCap Operation is supported using HTTP GET. This section describes the structure of a GET GetCap request. GetCap requests can also be preformed using HTTP POST; see the section on 'Requests Using HTTP POST' for guidance, below.
The VERSION parameter specifies the protocol version number. The format of the version number, and version negotiation between client and server, is discussed above. The parameter is optional, and when absent, the reply shall return the most recent version of which it is capable.
The REQUEST parameter specifies which Operation is being requested from the server. Although only GetCap is supported over HTTP GET, the all GetCap requests using HTTP GET shall employ the REQUEST parameter. This is to allow for use of the GET method if it is required for future request Operations.
The SECTION parameter specifies which type of capability is requested. The GetCap reply format currently provides the following types:
Service: Service metadata
availabledata: available datasets provided by the Service
capabilities: capabilities for each Operation
all: all of the above (default)
The parameter is optional and all elements of the GetCap shall be provided when absent. Multiple parameters may be delimited by commas, subject to the notes on Parameter Lists, above.
The EXCEPTIONS parameter specifies the format in which exception (error) information it returned from the server. See Chapter 11, Heritage Exchange Exceptions Format. The parameter is optional; "text/xml" shall be assumed when it is absent.
Here all defaults are assumed, so the resource URL is simply provided with defaults. All capabilities data is returned.
Example 9.2. Requesting specific capabilities
http://example.com/hep/?request=getcap§ion=availabledata |
This requests only information about the available datasets offered by a HEEP Service.
Example 9.3. Requesting multiple capabilities
http://example.com/hep/?request=getcap§ion=availabledata,Service |
This requests dataset metadata and Service information offered by a HEEP Service.
Example 9.4. Requesting specific exception format
http://example.com/hep/?request=getcap&exceptions=text/html |
This all default data, but requests that exceptions are reported in HTML.