Testbed-12 REST Architecture Engineering Report

This OGC Engineering Report (ER) is a deliverable (A005-1) in the Linked Data and Semantics (LDS) thread of the OGC Testbed 12 activity. It describes the different REST services developed in this thread as well as considerations and recommendations for a RESTful OGC architecture.

All questions regarding this document should be directed to the editor or the contributors:

The following work items have been identified as future work items:

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.

An interface definition that permits invoking services from application programs without knowing details of their internal implementation.

Hypermedia is an extension of the term hypertext. In addition to the general media information, e.g. graphics, audio, or video, hyperlinks are provided that enable browsing between different information items.

Representational State Transfer (REST) offers a clean, simple and easy-to-understand method of discovering, accessing and updating geospatial information. There is no special software to install. A web browser, a web application or a mobile app can be used to access the service directly - using standard HTTP methods (e.g. GET, PUT, POST, DELETE).

Representations describe the current or intended state of a resource at a certain point in time. A representation consists of a sequence of bytes and metadata to describe those bytes. As an example, a geographic feature resource may be represented by a GeoJSON document describing the spatial location and other feature properties or by a JPEG image providing a rendered representation of the feature. The media type definition provides the metadata needed to encode or decode the different representations.

Following Fielding [1], "any information that can be named can be a resource". Thereby, a resource is considered as a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at a particular point in time. Examples of resources in the geospatial domain are map tiles (served by a WMTS), features (served by a WFS), feature types (served by WFS), or observations (served by an SOS).

Representational State Transfer (REST) has been defined as an architectural style for distributed hypermedia systems by Roy Fielding in his doctoral dissertation [1]. The architectural style is defined by a set of constraints, which are described below. The core idea is that components of a REST-based architecture communicate primarily through the transfer of resource representations and additional control data which defines the actions upon these resources. In other words, the control data defines a set of pre-defined operations (usually HTTP verbs) to exchange and/or manipulate these representations, resulting in a uniform interface.

Web Service APIs complying to the REST constraints described above, are called RESTful APIs [3]. The vast majority of RESTful APIs available in the WWW are based on HTTP.

HTTP-based RESTful APIs are defined by:

Table 2 illustrates how HTTP methods are typically used in RESTful APIs.

HTTP GET is used for the retrieval of information. PUT can be used to update existing resource representations or collections. POST is used to create new resource representations and DELETE is used for deleting resources. In some cases, POST is used to create a new resource representation for a specific URL. However, this requires, that the client is (i) allowed to specify the resource identifiers and (ii) knows that no other resource is identified by the request URL.

Instead of specifying specific response codes, RESTful APIs utilize the common HTTP Status Codes (e.g. 200 for OK, 400 for bad request, etc.).

The REST APIs available in the Web are varying regarding the constraints that are supported. For example, not all REST APIs are supporting hypermedia. The Richardson Maturity Model (RMM) defines different levels indicating how strict a Web service is following the REST principles ranging from level 0 (not strict) to level 3 (strict). The different levels are listed in Table 3.

The advantages and disadvantages of using REST are liste in Table 4.

The probably most significant advantage of implementing REST APIs with hypermedia support is simplicity due to the uniform interface constraint. As most REST APIs utilize the HTTP verbs and JSON as hypermedia encoding, usual Web browsers supporting JSON formatting may provide a first entry point. More sophisticated thin Web clients may easily be build, because JSON is the default serialization format for JavaScript applications. However, keeping the interface specification quite general may also result in a variety of different REST APIs for the same purpose and dedicated clients for these APIs resulting in decreased interoperability. To address this issue, a set of recommendations has been derived in Clause 14.

Being stateless, REST improves reliability, as requests resulting in errors may be simply re-sent, and scalability, as no additional status information needs to be stored and managed. As a potential drawback, network traffic may be increased due to additional requests.

Another advantage is the ability for clients to cache representations improving performance and decreasing network traffic. However, if the representations are dynamically changing, this may become a drawback since information on the client side may be outdated or the update of representations may require additional client requests.

The geospatial services specified by the OGC are following a Service-oriented Architecture (SOA). The specifications thus describe the access and management of spatial data in terms of service operations. Resource-oriented Architectures (ROA) are defined from a different viewpoint: Instead of specifying service operations, a ROA focuses on the resources that should be managed by a server. In order to retrieve, create, update or delete these resources, the general HTTP methods (GET, POST, PUT, DELETE) are applied to these resources .

The transition from spatial data that is served by OGC Web Services towards resources offered in a OGC REST architecture is illustrated in Figure 2. In a first step, the service interfaces need to be translated to REST APIs, which includes the transition from Level 0 to Level 2 in Richardson Maturity Model. This boils down to to the following steps:

Unfortunately, as we will see in the chapters below, the translation is not as straight-forward as it may appear, since the OGC services have been specified from a service-oriented viewpoint focusing on operations rather than on resources. Therefore, step 1 is essential and needs to be executed with care. In order to illustrate the required steps, we use the OGC Sensor Observation Service (SOS; OGC 12-006), which provides access to sensor observations and sensor descriptions and transactional operations on them, as an example. In case of a consequent usage of hypermedia, the services as known in the SOA are no longer needed. This is explained in the last subsection of this chapter.

Technology Integration Experiments in this segment of Testbed 12, participants brought together three aspects of Testbed 12 -

In Testbed 12 Open Geospatial REST, WFS, NAS GML and GeoJSON were integrated by The Carbon Project to deploy a GeoJSON WFS REST.

http://ows12.azurewebsites.net/wfs/featuretypes/AdministrativeSubdivision

http://ows12.azurewebsites.net/wfs/featuretypes/AdministrativeSubdivision?outputFormat=json

Note: In most JSON WFS deployments there may be only JSON output format and the request would be directed to the Administrative Subdivision feature Resource. Simple query and transactions were tested with a focus on an initial assessment of NAS GML as GeoJSON.

Based on the experiences of Testbed 12, a GeoJSON WFS API may have significant potential to represent real world phenomena as open geospatial features as open geospatial REST Resources that can be accessed and updated using the language of the World Wide Web.

In the future, REST WFS may represent the Capabilities Resource as JSON Schema instead of current XML. There currently is no guidance for such metadata descriptions.

We can infer from the purpose of the GetFeatureInfo operation that the relevant resource is a “feature” and that a GeoJSON response would be considered a representation of that feature.

The WMS is a data portrayal service and as such, the only HTTP method used is the GET method which is used to retrieve the resources provided by the service (i.e. maps and feature info).

A WMS 1.3 server supporting GeoJSON as a GetFeatureInfo output format was deployed for Testbed 12 here:

http://tb12.cubewerx.com/a040/cubeserv?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities

The following example retrieves GeoJSON output is response to a GetFeatureInfo request:

The following GeoJSON document is retrieved by this URL:

Providing a GeoJSON response for WMS GetFeatureInfo requests makes a lot of sense, since more and more client applications are web-browser based and JSON is the more natural representation in this environment. However, OGC 15-053 imposes certain complications that were questioned, and ultimately discarded, in the implementation of A040.

OGC 15-053 states that "we are not recommending returning the full geometry description because we assume that this is the work of a WFS GetFeature operation using identifiers recovered by the GetFeatureInfo request". The justification for suggesting that returning a geometry is out of scope for a WMS GetFeatureInfo response was not clear. The entire point of having a WMS GetFeatureInfo request is to:

If a WMS client is interested in the geometry of a feature, it’s likely for the purpose of plotting it on the map to highlight the feature(s) that the user has clicked on. Wouldn’t it be convenient if the GeoJSON GetFeatureInfo response could include the geometry as part of the response? Of course, GeoJSON can do exactly that so we saw no reason for needlessly complicating the situation by bringing a WFS into the picture.

Furthermore, returning a vector pointing from the user click location (which client already knows) to "a point that is in the interior or the border of the returned feature" is completely useless to the client. Then requiring the client to somehow determine the association to the appropriate WFS server and WFS feature type (see discussion below), formulate and issue an appropriate WFS GetFeature request, and be equipped to handle the WFS response, is a lot to ask of a simple WMS client especially in the case where the client simply wants to highlight a feature on the map.

The requirements imposed on a WMS server by this aspect of requirement 28 are also overly onerous. The requirement is basically suggesting that if a WMS wants to be able to serve geometries to its client — so that it can highlight them on a map for example — then the WMS must also include an implementation of a WFS server to handle that. This all seems very heavyweight for no good reason, especially since GeoJSON responses are naturally equipped to return the geometries right from the start.

If the concern is that returning geometries in a WMS GetFeatureInfo response uses unnecessary bandwidth for client applications that don’t require the geometries, then our position is that using a bit of extra bandwidth like this is a small price to pay for the simplicity of the interface. The addition of two optional GetFeatureInfo parameters (Table 8) is proposed to streamline this:

The deployed TB12 implementation of the GetFeatureInfo operation includes these two parameters.

Finally, none of this is to say that returning the WFS feature identifier of the feature as part of the WMS GetFeatureInfo response is necessarily a bad thing. In fact, it might be useful to complex clients that really do need full WFS access to the feature (for example, to perform updates on it, etc.). It’s worth noting that a WFS feature identifier alone is not enough. The client application would have to also know:

The mechanism(s) to allow the determination of these associations was certainly beyond the scope of OGC 15-053r1. However, OGC 16-043, "Testbed-12 Web Integration Service Engineering Report", proposes just such a mechanism in Clause 6, "GetAssociations operation”.

According to the WMTS Specification (OGC 07-057r7), the resources provided by a WMTS REST server are listed in Table 9.

Besides the standard resources provided by a WMTS (i.e. tiles), if we define a TileJSON document of a layer to be a resource in and of itself, then the resource provided by A042 is a "TileJSON document".

The TileJSON document is defined by an open specification that can be found here: https://github.com/mapbox/tilejson-spec/tree/master/2.1.0. The document defines a very simple encoding for describing the availability of a WMTS Simple profile layer in Web Mercator.

The TileJSON-generating WMTS server was deployed in Testbed 12 at the following URL:

http://tb12.cubewerx.com/a042/cubeserv/default/wmts/1.0.0/WMTSCapabilities.xml

The following is a RESTful example of accessing a TileJSON document from this server using the HTTP GET method:

The following TileJSON document is retrieved by this URL (NOTE: Normally, packed JSON output is generated from by the A042 server but the output has been wrapped in this example to make it easier to read):

This exercise showed that the WMTS specification can be easily extended to support other tile-access strategies.

TileJSON essentially does what WMTS does, but in a more restrictive way, allowing only the Spherical Mercator coordinate system, a single layer, a single style, no extra dimensions, no feature-info querying, etc.. This makes TileJSON clients a bit easier to implement than WMTS clients (assuming that the restrictions of TileJSON are acceptable).

Adding TileJSON support to a WMTS could help allow a TileJSON client to use the WMTS. However, it’s not a perfect plug-in solution for TileJSON clients, because the WMTS capabilities document still needs to be parsed (either by a human or automatically) in order to determine the TileJSON URLs.

Now that is has been shown that a WMTS can generate a TileJSON document the question of whether all the necessary components are in place to build a REST-WMS/WMTS can be discussed.

The availability of TileJSON is orthogonal to the issue of REST. Its availability or not does not make a service any more or less RESTful. A TileJSON document is simply an alternative representation of a set of tile URL templates. The primary effects of the availability of TileJSON are:

On the issue of building a REST-WMS/WMTS, the WMTS is (depending on how rigorous your requirements for RESTfulness are) already a RESTful service. Its primary resources (i.e. tiles) are individually addressable via URL and there is a means of navigating from the service root to those resource via the tile URL templates advertised in the service metadata document (i.e. the capabilities document).

The WMS, on the other hand, cannot currently be considered a RESTful service. In some circumstances where the full flexibility of the WMS API is not required (e.g. building web-based geoportal applications) the WMTS can be considered a RESTful replacement for WMS. However, as already discussed in the "WMS REST Server" clause, the WMS is far more flexible and dynamic than the WMTS and would thus require its own RESTful API to be defined to properly cover all the requirements of a WMS.

Details about the WCS REST Protocol Binding can be found in the WCS REST extension draft. Synthesized, the protocol binding exposes all the functionality of the WCS service by mapping previously defined operations like GetCapabilities or DescribedCoverage to REST resources like Capabilities and CoverageDescription. Both the core and extension requests are covered by the protocol binding.

The implementation is based on the WCS Server of the rasdaman array database and extends it by adding a new Protocol Binding. The architecture of a typical server is described in the following diagram:

The REST implementation is using the Java Servlet API to parse the URL into meaningful fragments that are grouped together into a WCS Internal request that is independent of any specific protocol. The request is then passed to a service that handles the request and provides a response that can be returned to the user.

The Web Coverage Service is an operation-oriented web service and this made encoding the operations in a RESTful way slightly cumbersome. Most operations, for example subsetting, rangesubsetting and scaling can be mapped to resources, as any operation on a coverage will result in a coverage with different properties. However, the representation of these ad-hoc resources obtained from the original coverage do not add anything in particular to the existing KVP protocol binding which uses the same communication protocol (HTTP), same way of addressing the end result (URLs), same way of building the requests (constructing URLs as opposed to navigation through association links).

Associations between resources are unfortunately impossible to implement as the number of associations between certain resources is too large (a coverage has a virtually unlimited amount of subset coverage resources). Furthermore, no concrete method of describing an association between resources in the GML format is possible as far as we know.

Since the Capabilities are hard to use for describing the REST binding, the capabilities have been unchanged in the current implementation. However, a common way for describing the REST binding in a machine-readable manner needs to be developed in future versions.

Despite the shortcomings, the REST protocol binding proved simple to implement on top of an existing WCS platform and offers some advantages to users more accustomed to the REST approach in non-OGC services by defining resources that can be accessed through HTTP requests. The implementation done in this deliverable proves that the protocol is viable and can be implemented by service providers.

As there is not yet an official REST binding of the WPS available, the REST binding has been specified in Testbed 12. The resources that are provided by a WPS REST server are listed in Table 12 below and include the capabilities document of the server, the list of processes available (ProcessCollection and Process), jobs (running processes) and outputs of processes.

In general, the HTTP GET operation is used to provide access to the resources described above. However, in order to create a new job, the HTTP POST method is used to post a new job by sending a new job resource represented by an execute request to the server. This results in the operations listed in Table 13 below.

As stated above in the listing of resources (Table 12), the basic resources managed by the WPS REST server are processes, jobs, outputs and its corresponding collections. An overview on the associations between the resources is given in Figure 11.

The Capabilities has an association to the ProcessCollection that aggregates the single Processes offered by the Web Processing Server. The process has an association to the collection of jobs (JobCollection) that aggregates single jobs, i.e. instances that run a certain process.

The architecture of the 52°North WPS REST PI implementation is shown in Figure 12. The 52°North WPS REST API was realized as proxy to be able to test it with different WPS implementations during the specification process. The proxy was written in Java using the Spring framework and Jackson libraries for XML and JSON handling. The WPS requests and responses are handled using the 52°North WPS 2.0 XMLBeans. The underlying WPS was a 52°North WPS 2.0 instance, wrapping the Hootenanny conflation software.

In the following, example requests and responses for the different operations and resources will be shown.

The process summaries in the contents-section contain links to the process description of the respective process. The standalone list of processes can be requested as follows:

By default, the process will be executed asynchronously. If the process supports synchronous execution, this can be achieved by appending the following URL-parameter:

The direct response to a asynchronously executed process is HTTP status code 201 (created) and the URL to obtain status information and finally the result. The URL will be returned in a HTTP header named Location. For synchronous execution, the result document will be returned after the process has finished.

After the process has finished, the progress element will be replaced by the URL to obtain the outputs

The WPS REST API simplifies the interaction between servers and clients. The HTTP methods with its clear semantics ease to understand the interface and its communication pattern. The usage of hypermedia encoded as JSON allows clients to browse from the Capabilities to the processes available, to navigate from these processes to jobs (running instances of these processes) and, once a job is finished, to browse to the resulting outputs of a job. We hence submitted a change request (Request 396: Specify a REST binding for WPS 2.0) to the WPS SWG for defining a WPS REST binding based on the REST component developed in this testbed.

One difficulty encountered is the description of the API using the Capabilities document. In general, in order to interact with an HTTP based RESTful API, clients need to know

While the information about the resources offered can be easily embedded in the Contents section of the Capabilities document, the integration of the description about which HTTP methods are applicable on which resources is not straightforward. Usually, the OperationsMetadata section would be used for describing the operations offered, the endpoints and the operation parameter. However, since the OperationsMetadata have been defined for Web Services in Service-oriented Architectures, the description of REST APIs is not straightforward for the following reasons:

For this reason, we omitted the OperationsMetadata section and described the application of the HTTP methods in the specification draft. In future, it would be desirable to also offer a machine-readable description of the API relying upon existing description language, e.g. the OpenAPI specification [4].

The WaterML REST API has been published as a best practice document (OGC 15-033) resulting from the interoperability experiment testing the information model part 2 of WaterML (OGC 15-018r2). The REST API hence provides access to the following resources:

The RESTful API defined is currently a read-only service and thus only implements the HTTP GET method for resources.

An implementation of the REST API is available at

Since the resources returned contain links to other resources the RMM level is level 3.

The OGC SensorThings API Part 1: Sensing (15-078r6) is intended as a standard for connecting Internet of Things (IoT) devices as well as related data and applications via the Web. Currently, Part 1 of this standard is available which covers sensor observations. It supports the retrieval of observations of IoT devices and their related metadata. Tasking functionality will be covered by a separate part of this standard.

The following table provides an overview of the resources offered by the Sensor Things API:

It is important to note, that the Sensor Things API is, like the Sensor Observation Service (SOS), based on the general ISO/OGC Observations and Measurements model. As the functionality of the sensing part of the Sensor Things API is widely identical to the core operations of the SOS standard, a stronger harmonization would be recommended. In order to avoid confusion among potential operators and users, an idea could be to advance the Sensor Things API to become a REST binding of the SOS standard.

As can be seen in Table 16, hypermedia is not always returned due to the very different nature of geospatial information that is provided. While, for example, features served in GeoJSON may also easily include links to related features, it is more difficult to embed links in an image that is returned from a WMS server. Also, as stated in the lessons learned section of the WCS REST server description (Clause 10), in some cases there may be an infinite set of possible associations, e.g. a coverage resources has an unlimited number of associations to subset coverage resources. Since the subsetting is depending on the client and application, it does not make sense to provide only a subset of those associations.

In the lessons learned, all developers of the REST servers in Testbed 12 mentioned the simplicity of the implementations. This may be considered as a major improvement since especially the support of complex XML schemas with circular references was considered to be a major implementation task for the POX or SOAP based OGC services. Instead, requests are simply URLs that are invoked with different HTTP methods.

Since all OGC services inherit from the OWS Common specification (OGC 06-121r9), they need to provide a Capabilities document stating:

Hence, the Capabilities document is considered as an additional resource offered by the different OGC REST servers. However, the way how the Capabilities document is offered differs in the different implementations. WPS, WFS, and WCS are providing the Capabilities document at the base URL of the REST server, whereas the WMTS is providing it under a fixed subdomain (/capabilities), as specified in the WMTS specification (OGC 07-057r7).

In order to utilize a RESTful API, clients need to know

While the first information can be embedded in the Contents section of a Capabilities document (as shown, for example for the WPS REST server), the way how to access these resource or manipulate them cannot be simply mapped to the operations metadata section of the Capabilities. Hence, in case of WPS, for example, the decision was made to not provide the OperationsMetadata section (see also Clause 14).

Except the WCS REST server, all of the services are providing JSON encodings for at least some resources. Similarly to the support of hypermedia, the provision of resource representations as JSON is depending on the nature of the resources offer. While the encoding of geospatial features with vector geometries can be easily done using GeoJSON, a JSON encoding of Coverages or Map images provided by a WMS is not meaningful.

A special role is the encoding of the Capabilities document. So far, a dedicated mapping from the Capabilities elements to JSON does not exist. Rules how a mapping may be realized are currently defined in the JSON as an activity in this testbed. The WPS REST server provides an example how a JSON-encoded Capabilities document may look like (Clause 11).

There are three different types of associations in OGC REST APIs:

Furthermore a specific subtype may be links from a whole resource to sub-resources that are part of a larger resources. The association between coverages in coverage subsets may be consider as such an association.

The associations given in the resource representations are currently either given as embedded URLs in JSON (see Clause 11 for examples) or as ATOM links in RESTful WFS (see OGC 15-052r1). REST APIs supporting RMM Level 2 (WMS and WCS) are not providing the associations explicitly as links within data, but rather explicitly through their hierarchical URL templates.

A discussion has been held how to provide links for tile resources encoded as binary media types in a WMTS. A first suggestion was to define additional HTTP header parameters. Since there is already a Link parameter, it was agreed that this may be the right way to go, though this was not demonstrated by an implementation in Testbed 12.

The WMTS and WCS REST bindings are defining URL templates in order to construct the URLs for specific tiles or coverage subsets by replacing certain parts of an URL. For example, the URL template for retrieving a specific tile in WMTS looks like:

The parameter names between the curly brackets ('{' and '}') need to be replaced by a client in order to retrieve a specific tile, resulting in an URL like:

Since these APIs are not returning hypermedia (RMM Level 2), the URL templates are needed to specify the access to resources. In contrast, if, for example, the REST API is providing hypermedia, the Capabilities may serve as an entry point to the resources and the client can then navigate through the different resources and states following the HATEOAS principle.

The usage of URL templates is a source of dispute on the Web. The advantage of the approach is that there is a clear pre-defined structure for the resource identifiers and there is no need for hypermedia. Hence, the usage of URL templates appears to be appropriate for APIs at RMM level 2.

However, the approach also comes with disadvantages: The URL structure cannot be easily changed by the server, if, for example, also the resource model has changed, since the client is expecting the structure defined by the template. In addition, the approach contradicts the HATEOAS principle, since the URLs are not opaque and the links to resources are not given in hypermedia, but the a-priori specified URL template. Finally, there are also security concerns, since the URLs may be easily hackable to resources that are not officially published.

In the end, similarly to the support of JSON and hypermedia, the usage of URL templates depends on the nature of the data that is provided via the APIs: In case of coverages (WCS), maps (WMS), and map tiles (WMTS), the usage of URL templates is reasonable. In case the resource representations can be provided as hypermedia, there is no need for a pre-defined URL structure, if there is a pre-defined entry point to the resources, e.g. the Contents section of the Capabilities.

Several options are available to filter on resources in a RESTful API and to implement additional query parameters. The traditional way is to utilize the Key-Value-Pair approach, i.e. appending parameters to the URL. For example, when searching for features within a Bounding Box, the bbox parameter may be appended to the resource URL, applying the filter on the resource provided.

Another option would be to encode the bbox parameters in the URL and hence consider the result set laying in the bounding box as an additional resource offered by the REST server. This may look like:

However, this appears to be somewhat cumbersome since no template for encoding the bounding box parameters (minx, miny, maxx, maxy) currently exists. Furthermore, another open question would be, which resource is offered at a shorter path, e.g.

Similarly, several approaches exist to query the resource representations in a specific format, i.e. content negotiation. The common way to implement content negotiation is using the Accept parameter in the HTTP header. However, some other approaches exists in the current OGC REST APIs: The WFS REST server implemented in Testbed 12 utilizes the outputFormat parameter of the URL:

The WMTS specification suggests to append the file format extension to the URL, which may look like the following URL containing the ".xml" suffix at the end indicating that the XML media type is requested:

To sum up, no common approach for applying filters on the resources and additional parameters, e.g. for content negotiation currently exist.

Since there were no special requirements for security for the REST components, the only security method implemented has been HTTP Basic Authorization.

The current REST APIs implementing WMS, WMTS, WCS, WFS, and WPS vary in the RMM level that is supported. As described in the implementation sections (Clauses 7 to 11) and the previous discussion about the commonalities and differences (Clause 13), depending on the nature of the information that is offered, e.g. coverages vs. features, hypermedia may be returned or not.

Recommendation 1: If possible, OGC REST APIs should support RMM level 3.

The resources offered by a specific service type are defined in the service specification or data models referenced from the service specification. For example, as illustrated in Clause 6, the resources offered by a Sensor Observation Services (SOS) are defined in the Observations & Measurements (O&M) and Sensor Model Language (SensorML) standards. Similarly, the Web Feature Service offers features compliant to the General Feature Model.

Recommendation 2: The resources offered by an OGC W*S RESTful API should be compliant to the data specifications of the corresponding service specifications.

Furthermore, the resources should be identifiable by a unique identifier.

Recommendation 3: All OGC REST implementations shall follow the general REST requirement that resources are identifiable by an unique URI.

In addition, there should be an unique entry point for the resources. This recommendation is given below in the section about the API description and Capabilities document.

The associations given in the resource representations are currently either given as embedded URLs in JSON (see Clause 11 for examples), as ATOM links in RESTful WFS (see OGC 15-052r1) or using XML links in O&M XML. REST APIs supporting RMM Level 2 (WMS and WCS) are not providing the associations explicitly as links within data, but rather explicitly through their hierarchical URL templates.

Resulting from the varying encodings of associations, we define the following recommendations for REST APIs supporting RMM Level 3:

For each media type, a common way how to encode associations should be defined.

Recommendation 4: A unique way how to encode associations should be defined for different media types of OGC REST APIs.

In case the resource representation cannot be used to provide the associations inline, e.g. binary encoding of an image, associations to related resources should be given in the HTTP header using the Link parameter.

Recommendation 5: If links cannot be encoded in the resource representation returned, the Link param of the HTTP header should be used.

Currently, the semantics of associations are defined in the specification documents. One strength of hypermedia and linked data is to utilize explicitly defined semantics of the associations, e.g. in form of dictionaries or ontologies, that can be embedded in different linked data serializations, e.g. RDF or JSON-LD.

A couple of common vocabularies are already existing. One of the most prominent examples is the IANA Link Relations vocabulary [2].

Recommendation 6: OGC REST APIs should re-use existing vocabularies for describing link relations.

However, some of the special spatial relations like topological relations (e.g. within, intersects, etc.) are not covered by these vocabularies. Hence, these need to be specified and maintained by the OGC Naming Authority.

Recommendation 7: Associations representing spatial relationships should be specified by OGC and maintained by the OGC Naming Authority.

As shown in the previous Clause 13, there is currently no single way how the OGC REST APIs are described. Some are using plain XML documents without links to resources, others are embedding links to resources in the XML Capabilities, and others are providing a JSON encoding of the Capabilities with embedded links to resources. There is hence a need for harmonization of the different approaches.

One approach is to utilize the Capabilities document as an entry point to the resources. The WPS REST server developed in Testbed 12 (Clause 11) provides an example how this may look like. In addition the retrieval of the Capabilities document differs between the different REST APIs.

Recommendation 8: The Capabilities document should be provided at the root of the API endpoint.

Recommendation 9: The Capabilities document should provide an entry point to the resources offered by the API.

As there currently is not a concrete JSON encoding of the Capabilities document specified, the encodings vary as well. Hence, there is a need for a specification of a JSON encoding of the Capabilities document.

Recommendation 10: A JSON encoding of the Capabilities document should be specified.

If REST servers and clients would follow completely the HATEOAS principle, no further information would be needed, since requesting the allowed HTTP methods on a particular resource via the HTTP OPTIONS method would be sufficient. However, as in reality most of the REST APIs are not providing a full HATEOAS support, this information is needed in an API description. As stated above the OperationsMetadata is difficult to apply for the REST API description, in particular which HTTP methods need to be applied in order to retrieve or manipulate the resources offered by the OGC REST API. We hence suggest to also specify the provision of an additional API description file that is based on common Web standards already in use. One possible approach would be to utilize the OpenAPI specification and provide best practices how OpenAPI descriptions can be provided for OGC REST APIs.

Recommendation 11: The OGC should specify how an additional API description can be provided that defines how HTTP methods can be applied to the resources offered in order to retrieve or manipulate them.

As already stated in Clause 13, HTTP GET is used for retrieving resource representations. To create new resources, PUT or POST are usually used and DELETE for deleting resources. The REST binding for the WCS suggest to use the HTTP PATCH method for an partial update of a resource. This results in the following usage of HTTP methods:

Recommendation 12: OGC REST APIs should utilize the HTTP methods as shown in Table 17.

As common in REST APIs and illustrate already in the previous clauses, HTTP Status Codes should be used (e.g. 200 for OK, 400 for bad request, etc.).

Recommendation 13: OGC REST APIs should utilize the HTTP Status Codes in their responses.

A common use case is to apply spatial filters on collections of resources, e.g. the bounding box filter. As it is already common practice to utilize URL parameters for this purpose, it is also recommended to utilize them for applying filters to resource collection, for example:

Recommendation 14: Filters that should be applied to the resources should be given in the URL as URL parameters.

In the implementation of OGC REST APIs, different options mechanism for content negotiation are implemented. As using the ACCEPT parameter of the HTTP header is already common practice, we recommend to specify this option as mandatory.

Recommendation 15: Content negotiation should be implemented by OGC REST APIs using the ACCEPT parameter of HTTP headers.