ldesousa / ogcldapi

OGC LD API using FastAPI backened

OGC Linked Data API

An implementation of the Open Geospatial Consortium's (OGC) Features API Core.

This API framework uses Linked Data mechanisms, in particular Content Negotiation by Profile, to deliver human- and machine-readable data over the internet in several forms, including according to the OGC Features API. This is possible because the OGC Features API requires HTML and (Geo)JSON content for Features, Feature Collections, Geometries and so on, all of which can be represented as Linked Data via use of the OGC's GeoSPARQL 1.1 Specification.

API Structure

This API is a pure-Python API that implements a fixed structure matching that of the OGC Features API structure with a landing page, lists of Feature Collections and items (Features) within those collections.

Endpoint	API Path
Landing Page	/
Feature Collections	/collections
Collection X	/collections/X
Items in Collection X	/collections/X/items
Item Y in Collection X	/collections/X/items/Y

It also provides expected OpenAPI endpoints for API descriptions and a SPARQL Endpoint for graph structure equrying.

Endpoint	API Path
OpenAPI Specification in JSON	/spec
Auto-generated OpenAPI interactive HTML	/docs
Conformance class listing	/conformance
SPARQL endpoint	/sparql

Back-end

The API issues all requests for data to a separate RDF database ("triplestore") back-end. This is similar to issuing queries to any other database, such as a PostGres relationa DB. Figure 1 shows the main Python and back-end stack.

Figure 1: OGC LDAPI system overview

Python Dependencies

Conceptually, there are three main areas of functional dependency in this API:

1. Spatial
2. RDF (Linked Data)
3. FastAPI

Spatial includes packages such as geojson-rewind & geomet that do some small spatial data handling.

RDF includes rdflib & SPARQLWrapper which are used to either parse or serialise RDF data (the first) or interact with an RDF database (a 'rtiplestore') (the latter).

FastAPI includes packages related to the FastAPI web framework such as fastapi, starlette & uvicorn.

Installation

All the dependencies are available via the Python Package Index, PyPI, so you can "pip install" everything needed to run this API into a Python environment like this:

pip install -r app/requirements.txt

Use

There are a number of deployment patterns that can be used for FastAPI systems, we use the uvicorn Python web server.

We run this API both locally for testing and in production using uvicorn. All you really have to do is set a couple of environment variables and run the API instance via a single uvicorn call.

Environment variables

All environment variables except SPARQL_ENDPOINT are optional in that defaults often work. See config.py for the defaults.

Typically you might set these variables:

Variable	Purpose
SPARQL_ENDPOINT	The location of the RDF database
SPARQL_USERNAME	Username for above
SPARQL_PASSWORD	Password for above
DATASET_URI	The identifier of the Dataset in the RDF database for this API's data (the DB may contain lots of other stuff)
LANDING_PAGE_URL	The home page of this API. This may be left unset if the API is proxied to.
API_TITLE	A custom title for the API, displayed on many pages
HEADER	The URL of an online-accessible Jinja2 template for the header of each page. See app/templates/header_template.html. The API will pull this in on load so the template should be in something like GitHub.
FOOTER	As above, for a footer
STYLESHEET	A stylsheet for the API, as a file refered to via URL.

Simple, local

Locally, this just involves running a command list this:

uvicorn app:api --host 0.0.0.0 --port 9000

Docker

The Dockerfile supplied in this repo can build a Docker image that you can use to run this API in any Docker container system. We use Kubernetes on AWS.

Tests

Instances of this API are best tested with two sets of independent tests:

1. OGC API conformance tests
2. Content Negotiation by Profile (Linked Data) conformance tests

SURROUND maintains libraries of these tests and they will be published soon, and linked to from here.

You may also use other OGC API test suites.

Data

For RDF data to work with this API, it must be valid according to the OGC LD API Profile which is a standard requiring the data to have certain things, such as a dcat:Dataset declaration, geo:FeatureCollection instances and so on.

The profile provides bothe written requirements (the "Specification") as well as a SHACL data validator that can be used to automatically test data.

If your data passes all the validator tests, it will work with the API!

Assistance

This open source API and instances of it are commercially supported by the creator, SURROUND Australia Pty Ltd. Please contact SURROUND, via the Contact section below, for any help!

You can also log Issues in the Issue tracker of this repo:

• https://github.com/surroundaustralia/ogcldapi/issues

License

This code is licensed using the Apache licence. See the LICENSE file for the deed.

Note Citation below for attribution.

Citation

To cite this software, please use the following BibTex:

@software{surroundaustralia/ogcldapi,
  title = {OGC Linked Data API},
  version = {1.2},
  date = {2021},
  publisher = "SURROUND Australia Pty. Ltd.",
  url = {https://github.com/surroundaustralia/ogcldapi}
}

Contact

publisher:

SURROUND Australia Pty. Ltd.
https://surroundaustralia.com
[email protected]