-
Notifications
You must be signed in to change notification settings - Fork 8
Writing OpenAPI and JSON LD descriptors
An important concept of OpenRiskNet is the idea that we should try to make REST or similar HTTP based APIs semantically understandable for machines and humans. To do so, services should be accessible as REST like APIs (strictly speaking they mainly have to be HTTP based using text protocols like JSON). They then need an OpenAPI definition that describes them and this OpenAPI document has to be further annotated with semantic information using ontology terms. These prerequisites allow an OpenRiskNet service to be understood and queried using SparQL queries based on their semantic annotation. You can find out more about how these annotations work and how you can add them for your services here: Annotating-API-to-make-it-queryable
The other half of the annotation design of OpenRiskNet is that these annotations should be automatically found whenever a container of an OpenRiskNet service comes online within an OpenRiskNet Virtual Research Environment. To facilitat this, annotations on OpenShift/Kubernetes services are used by the OpenRiskNet Service Registry. For services that are not deployed within a VRE but that instead run on a server on the internet, a mechanism for external services can be used (manually maintained for now but with a curated official list coming soon). You can find out more about both approaches here: Annotating-your-service-to-make-it-discoverable
The following references may be useful background for the design of OpenRiskNet:
- Open API 3.0 Specification
- JSON-LD
- D2.2 and D2.4 reports to the EU describing the thinking behind the choice of OpenAPI and Json-LD.
TODO - provide other links and guidance to how to annotate your services.