Skip to content

Annotating your service to make it discoverable

Jump to bottom
Daniel Bachler edited this page Nov 18, 2019 · 6 revisions

This page describes how you incorporate your service into the OpenRiskNet registry once you have provided OpenAPI and JsonLD descriptors.

Services running as containers inside a VRE

This section only applies to services that run within an OpenRiskNet VRE. For services that run elsewhere on the internet these annotations below are not used and instead the registry can be informed about these external services and where to access their OpenAPI and JsonLD descriptors (see below).

The OpenRiskNet registry runs in the OpenRiskNet VRE and listens for service and routes starting or stopping. When one starts the registry inspects the OpenAPI+JsonLD definition and adds it to the list of known services. When it stops it is removed from the list.

An OpenShift service is used internally within the OpenShift cluster (e.g. by another service) and is not accessible from outside the cluster (e..g from your web browser).

And OpenShift route is a bridge from the outside to an OpenShift service (e.g. to allow a service to be accessed from your browser or an application running outside of the cluster.

To be recognised by the ORN registry your service need to be annotated like this:

kind: Service
metadata:
  annotations:
    openrisknet-static-services: <open-api-url>

The value of <open-api-url> should be the HTTP(s) endpoint where your OpenAPI definition resides.

Real examples can be found for:

What happens here is:

  1. The service or route starts in OpenShift and sends out a Kubernetes event for this.
  2. The OpenRiskNet registry listens for events for a service or route starting.
  3. When it finds such an event it inspects that annotations of the service looking for the openrisknet-static-services annotation.
  4. If it finds one it fetches the OpenAPI document at the URL specified by the annotation.
  5. That OpenAPI definition (along with its Json-LD additions) get incorporated into the registry and are presented as available services, and become queryable using SPARQL.
  6. The registry also listens for events for services and routes shutting down and when it finds these it removes those definitions from its database.

Services not running inside a VRE

For services that can not be easily deployed inside an OpenRiskNet VRE (e.g. big databases or commercial services), there exists a mechanism to add these to the registry so that they show up on the registry's user interface and can be found via semantic SPARQL queries. At the moment this is done by manually adding them to the registry (external services tab in the OpenRiskNet registry ) but a more principled solution to maintain an official repository of external services is in the works. In any case there needs to be an OpenRiskNet annotated OpenAPI document for the service in question.

Clone this wiki locally