rest approach

Overview

The ERDAS Apollo Catalog exposes its object model as a RESTful set of resources, each resource type having its dedicated URL endpoint.
REST is subject to an ongoing debate to define what it exactly is or isn't, and many REST-related concepts and questions are still looking for a clear answer. As there are currently as many understandings of REST as implementors, the following paragraphs do not intend to give a definite and abstract definition of REST, but rather describe the ERDAS take on a REST architecture.

Terms definition

The following terms must be clarified in the scope of the Apollo architecture.

• ROA: Resource Oriented Architecture; a software service architecture type that is resource-centric, as opposed to Remote Procedure Call (RPC) architecture that is process-centric
• REST: REpresentational State Transfer, as defined in Fielding's thesis. We consider REST as being an instance of ROA relying on the HTTP protocol; this is important for the comprehension of this document, as the term REST as it is used here will always refer to the HTTP implementation of a ROA
• URI: Uniform Resource Identifiers. Resources in a ROA must be identifiable by unique and static IDs; in REST these IDs are URIs that can be used to directly access the resource or to link to it in another resource representation.
• Representation: Resources are decoupled from their representations. A URI uniquely identifies a resource on the server, but the client interacts with the server using representation of resources. In a REST artchitecture, the representations are described by mime types
• Hyperlinking: Representations of resources must express links between resources using hypermedia links. In a REST architecture, the URIs of resources are used as hyperlinks

Accessing resources

Available HTTP endpoints

The following endpoints are available (the base URL to those URIs is /erdas-apollo/catalog/content) :

URL	Description
/items	All catalog items can be accessed via this endpoint
/services	OGC services
/services/resources	OGC services resources, i.e. map layers, features types, coverages
/services/{id}/resources	OGC services resources for one given service
/services/WFS	OGC WFS services
/services/WMS	OGC WMS services
/services/WCS	OGC WCS services
/coverages	Imagery coverages
/processes	WPS processes
/taxonomies	Taxonomies and dictionaries used to classify catalog records
/concepts	Concepts, i.e. classification elements from taxonomies
/contacts	Contact entities

Content negociation

As explained above, representation formats are identified with mime types. When querying, the format of a resource is decided using HTTP content negociation, i.e. using the HTTP Accept header.

Any HTTP client can use that header to specify a (set of) accepted mime types; the server will then choose the best available mime type, produce that representation and set the Content-Type response header to specify what mime type was eventually chosen for the representation.

For instance, a typical web browser will issue GET requests like

meaning that it prefers text/html, but can handle also application/xml.

The content negociation can be overridden by appending a format extension to the URI.
F.i., the resource /erdas-apollo/catalog/content/items will default to its HTML representation when accessed from a browser, but its JSON representation can be retrieved using /erdas-apollo/catalog/content/items.json.

File extensions are supported for all the formats described in the Formats section, i.e. :

• html
• ebxml
• json
• kml
• txt
• georss

Querying

The catalog resources can be retrieved and browsed using the URI patterns described above. Any of those URIs can be further filtered using a set URL parameters :

Parameter	Description
keywords	full text search on the catalog record content
intersect	spatial search using a WKT encoded geometry
bbox	spatial search by box, encoded as defined in the OpenSearchGeo specification
inurl	when retrieving services, filters on the service URL
orderby	orders results by the specified property (see the object model for available properties)
start	paging start index
maxresults	the maximum number of results to retrieve; defaults to 10
profile	the encoding profile to use; see the Formats section for an explanation of the available profiles

Examples :

OpenSearch

The OpenSearch specification defines a description language to describe web search engines. The OpenSearch Geo extension defines an extra set of spatial filtering parameters.

Offering an OpenSearch description identifies a web service as being a web search engine; OpenSearch clients such as today's browsers recognize it and can add that service in their list of search engines.
The Apollo Catalog offers such an OpenSearch Geo description; it is published in the head section of any HTML page of the catalog.

Advanced Querying

Complex queries can be submitted to the service on a dedicated endpoint.
Those queries are expressed in JSON, and must be sent using HTTP POST on the /content/search.json endpoint.

Examples of such queries can be found on the JSON Test page.