Skip to content

Annotating your service to make it discoverable

Daniel Bachler edited this page May 11, 2019 · 6 revisions

This page describes how you incorporate your service into the OpenRiskNet registry once you have provided OpenAPI and JsonLD descriptors. This 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.

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 the 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 ORN 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 it goes to the URL specified by the annotation and fetches the OpenAPI definition.
  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 if finds these it removes those definitions from its database.
Clone this wiki locally