API Specification

GeoHealthCheck API

Original API spec author: Jeroen Wisse (province of Zeeland, The Netherlands) General principles and conventions came out of an email exchange between Jeroen and Just van den Broecke in June 2020.

Background

As indicated in longstanding issue #20, having a (REST) API for GeoHealthCheck is desired for integrations with remote applications. In addition, the current thoughts for a future version of GeoHealthCheck also favor a "REST-API-GUI" architecture, where (web)client and server are completely decoupled via an API (i.s.o. the current approach with Flask and server-side Jinja2 templates).

So for these two reasons an activity to first design/define an API specification has been started in June 2020. In the first instance, the API will be based on the current implementation of GHC in order to facilitate remote clients for monitoring and reporting. So the first version of the API will only support READ. Later versions will support full CRUD.

This is a living document to define and brainstorm the first API version. Once stabilized it will move to the official GHC documentation. Work on this API is done via a dedicated issue. Please use that issue for comments and suggestions.

Current API Status

GHC already has some minimal REST API support. This was implemented ad-hoc, in order to support summary reporting and for plotting graphs:

https://demo.geohealthcheck.org/api/v1.0/summary/ of
https://demo.geohealthcheck.org/api/v1.0/summary.json
https://demo.geohealthcheck.org/api/v1.0/summary.html

# Get the "run" data from a specific Resource
https://demo.geohealthcheck.org/api/v1.0/runs/<resource_id>[.<content_type>
https://demo.geohealthcheck.org/api/v1.0/runs/27
https://demo.geohealthcheck.org/api/v1.0/runs/27.json
https://demo.geohealthcheck.org/api/v1.0/runs/27.html

Design Strategy

Some general principles, conventions and patterns.

API Standards

Will follow principles of the OpenAPI Specification - OAS - v3.

Resources

Within GHC the terminology for an service endpoint is Resource. This is the same term used in REST API design. To avoid confusion the "GHC Resource" is always written with a capital R. Plus we favor the term "endpoint" for API resources.

So the GHC Resource is the main API resource.

API URI Root

Will use the versioned existing convention, ie.

http[s]://<GHC instance URL>/api/v1.0

This root API should return a list of endpoints provided by the API.

Authentication

Is not supported in the first version.

Response format

Default JSON. Explicit formatting via f= parameter.

Requests

A GHC Resource is of a certain type, e.g. OGC:WMS. It can have one or more Tags. A Resource has one or more Probes. A Probe embodies the healthcheck itself. The Run is a the result of executing a Probe.

Below are the request URIs (GET). Note that each request is prefixed with /api/v1.0/.

URI	What
/resources	get all Resources
/resources/types	get all Types
/resources/types/{type}	get all Resources of type {type}
/resources/tags	get all Tags
/resources/tags/{tag}	get all Resources with Tag {tag}
/resources/{id}	get Resource with id {id}
/resources/{id}/probes	get Probes of Resource with id {id} (needed?)
/resources/{id}/probes/{probeID}	get Probe with probeID of Resource with id {id} (needed?)
/resources/{id}/runs	get Runs of Resource with id {id}
/resources/{id}/runs/{runID}	get Run with runID of Resource with id {id}
/resources/{id}/details	get details of Resource with id {id}