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 all Probes for a Resource.

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

URI	Parameters	Result
/resources	None	List of all the resources.
/resources/types	None	List of all the resource types.
/resources/types/{type}	type: The type of resource	List containing all resources of a specified type.
/resources/tags	None	List of all the tags for all resources.
/resources/tags/{tag}	tag: The tag describing the resources	List of all the resources containing this tag.
/resources/{id}	id: The id of the resource	The resource with its general properties.
/resources/{id}/probes	id: The id of the resource	A list of probes for this resource (needed?)
/resources/{id}/probes/{probeID}	id: The id of the resource, probeID: The id of the probe	Detailed information of the probe (needed?)
/resources/{id}/runs	id: The id of the resource	A list of runs for this resource
/resources/{id}/runs/{runID}	id: The id of the resource - runID: The id of the run	Detailed information of the run.
/resources/{id}/details	id: The id of the resource	The details of the resource.

Response Data

Resources properties

Property	Type	Description
Id	integer	The unique id representing this Resource.
Name	string	The name of this Resource.
Type	string	The Resource type, for example OGC:WMS
Enabled	Boolean	Is this resource enabled?
Tags	string array	List of tags for this resource
Owner	string	The owner of this resource
Run_every	integer	The interval (minutes) at which this resource runs its probes
LastRunID	integer	The ID of the last run, can be used to get information of the last run via /resources/{id}/runs/{LastRunID}.

Resource Details properties

Property	Type	Description
Authentication	object	The authentication details for this resource
Notify emails	string array	List of email addresses used for notifying on status change of the resource
Notify web hooks	string array	List of web hooks used for notifying on status change

Run properties

Property	Type	Description
Id	integer	The unique id representing this run.
Result	boolean	The result of the this run.
DateTime	string (ISO 8601 formatted)	The date and time of this run.
Error message	string	Optional the error message returned by the probe.