deegree OGC API - Features Implementation

The OGC API family of standards are being developed to make it easy for anyone to provide geospatial data to the web. These standards build upon the legacy of the OGC Web Service standards (WMS, WFS, WCS, WPS, etc.), but define resource-centric APIs that take advantage of modern web development practices.

Read more at www.ogcapi.org about the new standards and their goals. The OGC E-learning tutorial provides a chapter about the new standards and explains the basic concepts.

deegree OAF supports the following Konformitätsklassen:

Based on that requirements class deegree OAF provides implementations of representations for spatial data using encodings such as:

The Web API is provided as an Open API 3.0 document implementing the requirements class:

deegree OAF was built on top of the robust API and configuration concept of deegree webservices. Notable features:

Is a collection of data. In the context of deegree OAF a dataset is the set of feature types provided by a feature store. It is identified by it’s {datasetId}.

Is a source containing data retrieved from a file or a database. In the context of deegree OAF a datasource can be a feature store implementation. Which feature store implementations are supported is explaind in section Feature store configuration.

Is an abstraction of real world phenomena. In the context of deegree OAF it is a spatial entity stored in a datasource. It is identified by it’s {featureId}.

Is a set of features from a dataset. It is identified by it’s {collectionId}.

Is a ressource within the deegree workspace providing access to stored features. In the context of deegree OAF a feature store provides access to datasource such as SHAPE file or a database.

Is a description of the dataset. In the context of deegree OAF metadata can be linked per dataset.

An API using an architectural style that is based upon open standards and best practices such as OpenAPI Specification and it’s implementation Swagger.

Is a deployable instance of a web application. In the context of deegree OAF it is a Web application ARchive (WAR) containing all resources that together constitute the deegree OAF application.

Is a directory structure containing configuration files. Most configuration files are in XML format. Read more in Configuration how to configure deegree OAF.

deegree OAF works on every Java Servlet container implementing the Java Servlet API 3.1 using an OpenJDK or Oracle JRE 11. The JRE and Java Servlet container constitute the runtime environment. The installation of these components must be done prior of this installation.

The server hosting the service should have at least 4 GB of free memory and more than 2 CPU cores available.

The deegree OGC API webapp is provided as a web application archive (WAR) file and release versions are available on the deegree OGC API GitHub page.

Choose either the deegree-ogcapi-webapp-postgres.war for PostgreSQL/PostGIS or the deegree-ogcapi-webapp-oracle.war for Oracle databases. Both webapps contain all required libraries and feature store implementations to access file-based feature stores (see Feature store configuration for more information which feature stores are supported). Download the WAR file and store it in the local file system of the server.

Move the WAR file to the deployment folder of the runtime environment. For Apache Tomcat the folder is $CATALINA_HOME/webapps.

To start the webapp the runtime environment needs to be started. For Apache Tomcat use the start script $CATALINA/bin/startup.sh.

To stop the webapp the runtime environment needs to be stopped. For Apache Tomcat use the start script $CATALINA/bin/shutdown.sh.

To uninstall the webapp:

Docker images with deegree OGC API are available on Docker Hub. This requires the installation of Docker on the server. Check the Docker documentation for requirements and installation instructions. The docker image provides all software components and no additional software installations are necessary.

Get the docker image with:

To start a Docker container with the name ogcapi on port 8080 run the following command:

See the Docker CLI documentation for more information how to connect a container to a network, mount a volume into the container, or set environment variables.

deegree OAF has been tested across a wide range of browsers, and operating systems.

The following browsers are supported:

If you are not using one of the browser above, you should be able to access all resources provided by deegree OAF and use the HTML pages but it might not display the site as designed, nor provide you with the best user experience.

Some browsers, particularly earlier versions, either do not or only partly support W3C standards and JavaScript. These browsers might not display the HTML pages properly. See the list of supported browsers by the Vue.js framework for more information.

The deegree workspace is the modular, resource-oriented and extensible configuration concept used by deegree. The deegree OAF workspace is an extension of the standard deegree workspace. A deegree OAF workspace can contain additional configuration files specific to deegree OAF.

The directory structure and related files are described by the following example. This example consists out of two datasets called trees and streets which data is stored within a PostgreSQL/PostGIS database. The following directory structure shows the files used in this example:

More information about deegree’s workspace concept is available in the deegree webservices handbook. There you will find more information about the feature store configuration and the JDBC connection configuration.

The deegree OAF workspace adds the following directories to a standard deegree workspace:

A deegree OAF workspace uses the following directories of a standard deegree workspace:

The following chapters describe how to setup a deegree OAF workspace by the given example.

deegree OAF provides a REST-API for configuration purposes. As in deegree webservices a client can use the REST interface to manage the configuration. The following operations are supported:

The REST-API is enabled by default. To protect this interface from unauthorized use, it is automatically secured with a so-called API key. Each HTTP request requires that the API key contained in the file config.apikey is transferred.

A detailed documentation of the REST-API interface and how access is configured is described in section "deegree REST interface" of the deegree webservices handbook.

In case you want to avoid any issues when using the OpenAPI document from other locations due to CORS, you can enable allowing all origins specifically for accessing the OpenAPI document. To enable this set the system property deegree.oaf.openapi.cors.allow_all to true.

This resource provides an overview of all datasets served by deegree OAF:

All resources are available in different encodings. To request a resource in a different encoding the client shall use either the HTTP Accept header or the query parameter f to retrieve the data in the requested media type. To retrieve the supported media types per resource use the OpenAPI document available under '/api'.

Besides the resources listed above for each dataset all resources defined by the OGC API - Features standard are supported. The configuration examples described in this document would result to the following addresses for each dataset. The landing page for the dataset trees would be served under the address http://localhost:8080/deegree-services-oaf/datasets/trees and the landing page for the dataset streets would be served under the address http://localhost:8080/deegree-services-oaf/datasets/streets.

The following table show the resources available per dataset:

The OpenAPI page is available under the context /api or /openapi. The use of /api on the server is optional and the API definition may be hosted on completely separate server. If you have deployed the deegree OAF webapp under the context of deegree-services-oaf and you have a dataset configured with the name streets the resulting request path would be /deegree-services-oaf/datasets/streets/api.

The interface is grouped in the sections:

For all resources listed on the first three sections the following description explains how to send a request and retrieve the response in a given encoding.

Use the generic OpenAPI specification HTML page to make a request.

Example request: Get Landing page in json encoding.

The page should display the server response in the selected encoding and the HTTP status code. In addition the HTTP response header information is displayed.

To access a response in the requested encoding directly use either the given command line tool curl with the given options as displayed in the OpenAPI page when sending a request described in section Making a request. Or use a browser and additional plugins to send the HTTP request directly. Use the HTTP Accept header or the query parameter f to define the expected response format.

To retrieve a resource in application/json encoding use the request parameter f=json. To retrieve the landing page of the dataset streets in application/json encoding use the following request datasets/streets/?f=json. Example URL: http://localhost:8080/deegree-services-oaf/datasets/streets/?f=json

See section Using query parameters for more information about other supported query parameters.

To retrieve a resource in application/xml encoding use the request parameter f=xml. To retrieve the landing page of the dataset streets in application/xml encoding use the following request datasets/streets/?f=xml. Example URL: http://localhost:8080/deegree-services-oaf/datasets/streets/?f=xml

See section Using query parameters for more information about supported other query parameters.

The corresponding GML schema file is provided under the resource of each Feature collection datasets/{datasetId}/collections/{collectionId}/appschema. Example URL: https://localhost:8080/deegree-services-oaf/datasets/streets/collections/streets/appschema

The HTML interface provides easy access to the spatial data using a browser (check the list of Supported Browser). It requires no additional client or browser plugin to browse the data. The browser sends by default the HTTP header Accept with the value text/html and therefore each resource is returned in HTML encoding.

To browse the data open the browser of your choice and start at the datasets overview available at datasets/. Example URL: http://localhost:8080/deegree-services-oaf/datasets

Navigate to the landing page of the dataset trees by clicking on the link "Landing page as HTML".

The landing page provides links to all resources of a dataset.

When navigating to the feature collections and feature collection resource links to access the referenced metadata and bulk download in GeoJson and GML encoding are provided.

The following query parameters are supported when using HTTP GET:

Use the deegree support options (mailing lists, commercial support) to get help.