-
-
Notifications
You must be signed in to change notification settings - Fork 70
API Specification
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.
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.
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
Some general principles, conventions and patterns.
Will follow principles of the OpenAPI Specification - OAS - v3.
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.
So the GHC Resource is the main API resource.
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.