Testbed-12 REST User Guide

There are almost as many definitions of REST as people using it. As stated above, 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, structured URLs or whether it is ‘allowed’ to include ‘query parameters’ in a URL. 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.

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.

An example of making a request to a Feature Resource is shown below. In this example, an application needs to get the boundary of the state of California. To do this, it sends an HTTP request to the Resource at the URL indicated.

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 HTTP verbs can make many things easier for API developers and client applications. For example, if an application needs to change something in the California boundary feature it simply sends an HTTP PUT with information to update the Feature Resource.

So, where possible, open geospatial REST strives to use HTTP verbs for each action against a Resource –

HTTP methods are characterized as safe and/or idempotent and servers should be mindful when processing HTTP requests to not violate the safety and/or idempotence of the requested method. Safe methods are methods that do not modify the representation of a resource and so their results can be safely cached. Idempotent methods are methods that can be repeatedly processed but their effect will always be the same.

HTTP Status Codes like the ‘200 OK’, '400 Invalid Request' or '404 Not Found' are used in accordance with the HTTP 1.1 specification.

HTTP methods on resources are subject to authentication and access control (e.g. someone who does not have authorization to create new features would not see the POST methods when interrogating a resource with the OPTIONS method). Authentication and access control are envisioned to be layered on top of RESTful resources.

At this point, an enterprise architect may expect that all open geospatial Resources must available on a server. But this is not the case. Conceptually, and from the client’s perspective, an open geospatial Resource is available even if serving it involves dynamic generation. For example, in the case of a REST WMTS it may be more practical to render Tile Resources on-the-fly than creating and storing billions of small images. This is because to create and store all the possible Resources for a time-queryable REST WMTS you would have to multiply billions of tile positions by every allowed open-ended interval to fully pre-generate them. With 19+ digits of freedom on each end of an arbitrary time interval, you end up with ~10⁴⁷ possible REST Resource URLs, or quattuordecillions of them. So it may be more practical to generate some Resources ‘on the fly’.

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.

At this point it’s 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.

Using the example of a WMTS again, 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. The syntax of a URI template is to enclose the parameters in braces, like this {{example}}. Another example is provided below…

If we examine the URL in the example…

https://tb12b.cubewerx.com/cubewerx/OpenImageMap/tilesets/PolarASAR/PolarASAR/default/interval:2012-01-20T11:22:33.444555666—​2012-02-06T22:33:44.555666777/smerc/5/6/9.jop

…we can see it is the result of a URI template that’s otherwise fully opaque, which means clients shouldn’t attempt to construct their own (beyond the prescribed variable substitutions). In this example the URI template reported by the Capabilities Resource (metadata) is:

https://tb12b.cubewerx.com/cubewerx/OpenImageMap/tilesets/PolarASAR/PolarASAR/default/{QTime}/smerc/{TileMatrix}/{TileRow}/{TileCol}

But the URI template could just as well have been:

https://foo.com/foo{TileCol}foo{QTime}foo{TileRow}foo{TileMatrix}

URI templates are useful at all Levels, depending on the open geospatial Resource type and access paths needed.

Since the client shouldn’t attempt to interpret URI Templates and shouldn’t attempt to construct their own, whether or not the URL contains a version number or service identification and what its location and syntax is entirely up to the needs of the server. That’s one of the powers of the URI Template - the client requires no knowledge of the structures of the URLs beyond the URI Template variables, and the server is free to use whatever URLs are most convenient for it.

Given this possible variability, a starting point is useful to answer three questions about relevant open geospatial Resources - "What are they?", "How do I get to them?", and "How do I get the things they may provide?".

To help answer these questions the Capabilities Resource provides a complete metadata document for other Resources offered. Interactions with a set of OGC Resources usually commences by accessing the Capabilities document.

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. This situation is the result of supporting previous methods while being new methods into the interoperability architecture.

The versions supported are also stated in the Capabilities Resource. If a service supports several versions, these may be advertised in different Capabilities documents provided at different endpoints, For example, for Resources associated with processing functions this would be -

http://my.url.com/wps-rest/1.0

and

http://my.url.com/wps-rest/2.0

For Resources associated with features this would be -

http://www.someserver.com/wfs/1.0.0

and

http://www.someserver.com/wfs/2.0

and so on.

The Service Root and well-formed Base URLs bring up another key point. OGC Web Services have long-been criticized because nothing was available at the service URL - unless you appended a Request=GetCapabilities KVP. The starting points Service Root and well-formed Base URLs address this issue by providing both human and machine readable information about the 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.

At Level 3 we can also begin to look at Resource constructs such as hypermedia controls in general. 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.

In addition, 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 some examples are included in the graphic below.

Associations are linkages between Resources, and can help break down the ‘stovepipes’ between open geospatial Resources. For example, an Association can indicate the source data set for a web map (the Association below is 'renders') -

Finally, it should be noted that REST is often viewed as synonymous with JSON. But REST does not restrict data transfer to a single encoding like JSON, or communication to a particular protocol like HTTP. However, the protocol designated for interface between Components in Testbed 12 is HTTP.

Open geospatial REST also allows applications to select the encoding format that is most useful to their mission. For example, Resources can be represented in different encodings such as XML or JSON, depending on whether applications need complex analytics or simpler representations like web display.

With these key concepts you can begin to understand the basics of open geospatial Resources and REST. To better understand REST in the context of offering geospatial information and services you also need to know the Principles of REST and some of its advantages.

The term 'REST' was coined by Roy Fielding in Ph.D. dissertation in 2000. Since that document hundreds of systems architects have tried to establish one definition of a REST Architecture - usually resulting in an unfinished argument. This is because REST is not an architecture. It’s a set of principles that guide the development of a system that has resources, resource identifiers (e.g. URL), representations and connectors (e.g. clients, servers).

One interesting item to note is that the initial version of OGC Web Services were designed before Roy Fielding published his Ph.D. dissertation in 2000. So the answer to the question of "Why didn’t OGC Web Services use Fielding’s REST?" is…​ "Well, it didn’t really exist."

It’s also important to remember that many high-level principles of REST can seem rather Zen-like when you first read them. However, remember that in Testbed 12 we limit things to HTTP, so things can start to fall into place.

With these considerations in mind, when considering REST for delivering geospatial data and services some high-level principles of REST include:

But before you think that 'Web Services' must be abandoned some other key points are …​

With these principles in mind, when trying to decide to use (or not use) REST to offer geospatial information and services it is important to remember that REST is not a 'one size fits all' proposition. There are different levels of REST ranging from not RESTful to what may be considered 'fully RESTful'. These were discussed in the previous section as Levels 0 to 3.

With an understanding of Resources, HTTP verbs, principles and levels, enterprises should be aware of some of the advantages of using REST to offer geospatial information and services. These advantages include -

The following key terms and examples are presented in an order designed help the reader quickly get a better understanding the basics of REST for geospatial information and services.

You’ll see this guidance in almost every REST guide, but it’s there for a reason. For every open geospatial Resource use this guide.

Do not use verbs:

/getmaps

/createmaps

/deletemaps

At this point, most people familiar with geospatial technology will want to add more complexity. But for many geospatial enterprise APIs it’s not needed.

Many thanks to Stefan Jauker for the inspiration for the above table. Note: The Resource 'maps' is used for illustrative purposes only.

Testbed 12 defined over 20 open geospatial Resource Classes (below). Geospatial Enterprises should use these well-known definitions their APIs.

The HTTP standard provides dozens of status codes to describe return values. These codes let client applications know when things go wrong, and also when they go right.

Not all HTTP Status Codes may be needed and the table below provides a short list of the most useful ones for open geospatial REST.

An example of the HTTP Status Code used after creating a feature Resource is shown below.

This section provides examples of REST URL structures and Access Paths from Testbed 12.

This section presents Testbed 12 experience using open geospatial REST and JSON.

API management is a crucial software engineering functions for any organization trying to decide whether to use open geospatial REST to offer data and services. As the popularity of REST APIs has grown in the past few years, so too have the tools, best practices and consulting services that support organizations in API management. While these tools were initially developed for organizations to manage their organization-specific APIs, the tools can also be considered for use in API design in an open standards context. In particular, Testbed 12 participants have found the OpenAPI Specification, formerly known as the Swagger specification, to be helpful.

Documenting APIs can be aided by using the approach of the OpenAPI Initiative (OAI). OAI is focused on defining a vendor neutral API Description Format based on the Open API Specification (OAS). The approach will allow specification of REST APIs using modular sub-elements. Subelements can then live on their own and be shared by multiple APIs.

Providing complete documentation of your API using OpenAPI is a W3C Data on the Web Best Practice. This best practice for APIs is being discussed in the OGC/W3C Spatial Data on the Web Working Group.

It is recommended that enterprises make use of automated API documentation where possible. These can often be synched directly with an implementation version, which helps to minimize divergence. Some also provide interactive (e.g. Swagger) documentation that allows inline requests to be made. This helps to lower the barrier of entry for developers and quickly builds understanding of the REST API.