Publication Date: 2017-05-16

Approval Date: 2017-02-20

Posted Date: 2016-11-16

Reference number of this document: OGC 16-057r1

Reference URL for this document: http://www.opengis.net/doc/PER/t12-A060

Category: User Guide

Editor: Jeff Harrison

Title: Testbed-12 REST Users Guide


COPYRIGHT

Copyright © 2017 Open Geospatial Consortium. To obtain additional rights of use, visit http://www.opengeospatial.org/

Important

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights. Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

Note

This document is a user guide created as a deliverable in the OGC Innovation Program (formerly OGC Interoperability Program) as a user guide to the work of that initiative and is not an official position of the OGC membership. There may be additional valid approaches beyond what is described in this user guide.


POINTS OF CONTACT

Name

Organization

Jeff Harrison (Editor)

The Carbon Project

Simon Jirka

52°North GmbH

Christoph Stasch

52°North GmbH

Peter Vretanos

CubeWerx

Keith Pomakis

CubeWerx

Craig Bruce

CubeWerx

Charles Heazel

Wisc Enterprises

Stephane Fellah

Image Matters

Dave Wesloh

NGA


1. Executive Summary

This document presents a User’s Guide for open geospatial REST. It complements Testbed 12 architecture documents to assist enterprise implementers. The content is presented from the perspective of a person or organization trying to decide to use (or not use) open geospatial REST to offer data and services.

There are almost as many definitions of REST as people using it. Simply put, REST is a method of discovering, accessing and updating geospatial content using the standards of the World Wide Web – Resources, HTTP methods (GET, PUT, DELETE etc.) and hypermedia controls. However, there’s often confusion in the geospatial community over ‘What is RESTful?’. Lengthy email threads have discussed whether you must use hypermedia, or structured URLs. Previous efforts have even gone to great length to list diverse OGC documents with ‘REST’ in the title. These discussions don’t help the central challenge – how do we make it easy to access open geospatial information, and answer key questions about the world around us?

To meet this challenge, it’s important to recognize that REST isn’t a single, monolithic approach. It doesn’t even have to apply only to the Web. However, for the purposes of this guide we limit REST to the Web (i.e. HTTP) - and then break it down into four Levels. These Levels are derived for the Richardson Maturity Model (RMM).

The four Levels progress from Services to a focus on geospatial Resources, HTTP Verbs and linking Resources. A simplified representation of this Services → Resources → Associations progression is presented in the graphic below. Basic guidance is also provided at each Level. It’s important to recognize that these Levels aren’t discrete and exclusive – they build upon each other to help geospatial interoperability.

Picture10
Figure 1. A simplified representation of the Richardson Maturity Model (RMM) progression from Services to Associations

Starting at Level 0 the focus is on making requests to ‘Services’ using HTTP as a transport system for our remote interactions, often with XML. Level 0 represents the current state of many OGC Web Services. At Level 1 an enterprise can start to identify open geospatial Resources and then make requests to the Resources. An open geospatial Resource is geospatial information, like a feature or satellite imagery data, that can be identified by a URL.

Since REST is Resource oriented and the standard OGC web architecture is service oriented some adaptation of prior OGC service model is required. However, rather than completely redefining OGC Web Services, Testbed 12 has taken an evolutionary approach in developing the REST bindings that reuse as much of OGC Web Services functions as possible – but update things to work RESTfully.

At Level 2, a geospatial enterprise may begin using the HTTP ‘verbs’ the same way they are used in HTTP itself. This means we don’t define unique ‘Operations’ like INSERT, UPDATE, DELETE to access or modify Features and other open geospatial Resources. Instead, we use HTTP methods like GET, POST, PUT, DELETE. Using these HTTP methods can make many things easier for API developers and client applications and, where possible, open geospatial REST strives to HTTP verbs for each action against a Resource –

  • GET

    • Retrieve a Resource

  • POST

    • Create a new Resource

  • PUT

    • Update an existing Resource

  • DELETE

    • Remove a Resource

With Resources defined and HTTP verbs in use, at Level 3 we begin to focus is on hypermedia and Associations. That means we start building links between related open geospatial Resources. For example, hypermedia links may be used to link metadata to different information models or schemas. In addition, a Map Resource may have Associations to the satellite image data that it comes from.

It’s also very important to recognize that open geospatial Resources can include very complex information about the Earth – such as electro-optical, infrared, multispectral, hyperspectral and radar satellite measurements, map tiles, sensor observations and much more. This means that as much as we want all Resources to fit neatly into Level 1, 2 or 3, the reality is some open geospatial Resources are better suited to certain URL structures or Levels.

Picture13
Figure 2. Types of Geospatial Resources fit better at different Levels

Using the example of a WMTS (Web Map Tile Service), it wouldn’t be practical to navigate to quattuordecillions of time-varying Tiles via hyperlinks at ‘Level 3’. But a metadata description for open geospatial Resources may contain many useful hypermedia controls to navigate to different Resources.

As we consider URL structures another key concept for open geospatial Resources is the URI Template. A URI template establishes the structure of a URI (Resource URL) by indicating what values (parameters) can be added and what they represent. URI templates are useful at all Levels, depending on the open geospatial Resource type and access paths needed.

The Capabilities Resource provides a complete metadata document for other Resources offered. The Capabilities Resource should include hypermedia controls (i.e. links) that let a client application move from the Capabilities to the other Resources offered. Applications can also go directly to the Resources if they know how. Current OGC REST documentation describes two ways, the ‘Base URL’ and ‘Service Root’ to get to the Capabilities Resource. A Service Root is an actual URL where the Capabilities Resource exists. A Base URL is a URL prefix that the client appends parameters to in order to arrive at a valid request URL, including a request URL for the Capabilities Resource. Future open geospatial architectures will need to decide if they will support interfaces that require appending parameters to a Base URL, or can they just skip the middle-man and deal in URLs (and/or URI templates) directly – or do both.

At Level 3 we can also begin to look at Resource constructs such as hypermedia controls. Hypermedia controls allow an application to obtain the URIs for Resources it needs by following links in the representation of the Resources themselves - not by relying on out-of-band information like URI patterns given in documentation. For example, the response to a query for features should include links that tell the client how to get the capabilities document of the service that offers the feature; of which feature collection the feature is a member; which feature is next in the current results set; what alternative representations of the feature are available.

Finally, at Level 3 enterprises can start to build Associations between open geospatial Resources. As of Testbed 12, Associations are just beginning to be defined in open geospatial REST but they are essentially linkages between Resources. can help break down the ‘stovepipes’ between open geospatial Resources. Some examples are included in the graphic below.

Picture15
Figure 3. Level 3 Hypermedia - Associations

As a geospatial enterprise begins to implement the four Levels discussed, it is possible to make it easy to access open geospatial information, and answer key questions about the world around us.

2. Introduction

In 1999 OGC started developing a suite of web services for geospatial interoperability. These included web map services (WMS), web map tiling services (WMTS), web feature services (WFS), web coverage services (WCS), catalogue services (CSW), the Sensor Web services, etc.

For the most part these were developed using HTTP as a tunneling mechanism for remote interactions, usually sending Key Value Pairs (KVP) or plain old XML (POX) back and forth. As OGC web services started to use SOAP it was basically the same mechanism, the only difference was the messages were wrapped in an XML ‘envelope’. All these methods worked, but more and more specialized tools were required to access and use open geospatial data – costing time and money.

As years passed simpler alternatives became more popular. In particular, an approach called ‘REST’ began to be explored throughout the geospatial community. REST uses the standard language of the World Wide Web, HTTP, to discover, access and update geospatial resources.

This document presents a User’s Guide for open geospatial REST. It complements Testbed 12 architecture documents to assist enterprise implementers. The content is presented from the perspective of a person or organization trying to decide to use (or not use) open geospatial REST to offer data and services.