Annotating API to make it queryable

This page describes how you annotate your OpenAPI/Swagger definition to be queryable by the OpenRiskNet SPARQL service.

Purpose

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 fulfill this purpose, we combine several technologies:

• OpenAPI for documenting the technical API structure (HTTP endpoints, json structure of responses and requests, ...). This can be parsed by various tools to e.g. generate client libraries automatically for specific APIs but also to generate interactive documentation for human developers (e.g. you can follow the View in SwaggerUI link on any service in the ORN registry.
• JsonLD in the OpenAPI json document to be able to transform the entire OpenAPI document into the RDF data model and use ontology annotations. This can be done on a high level of operations as well as on a fine-grained level of individual json keys in the request and response descriptions by mapping json keys to ontology terms.

High level annotation

The very first entry will describe your service as an OpenRiskNet service.

openapi: 3.0.0
x-orn-@id: 'https://lazar.prod.openrisknet.org'
x-orn-@type: 'x-orn:Service'

and will be translated into:

subject	predicate	object
https://lazar.prod.openrisknet.org/	http://www.w3.org/1999/02/22-rdf-syntax-ns#type	http://openrisknet.org/schema#Service

The following code shows the annotation of a single route: (The whole API can be found here)

'/compound/{InChI}':
  get:
    x-orn-@type: 'x-orn:Compound'
    'x-orn:path': 'https://lazar.prod.openrisknet.org/compound/{InChI}'
    'x-orn:method': Get
    tags:
      - compound
    description: Get compound representation
    parameters:
      - $ref: '#/components/parameters/inchi'
      - $ref: '#/components/parameters/subjectid'
    responses:
      '200':
        description: OK
        content:
          application/json:
            'x-orn:returns': application/json
            schema:
              'x-orn:property': InChI
              type: string
              example: InChI=1S/C6H6/c1-2-4-6-5-3-1/h1-6H

Each orn annotations will be used to translate lines of code into RDF triples. For parameters a reference was used. This reference fully described is:

parameters:
    inchi:
      name: InChI
      in: path
      description: InChI String
      required: true
      schema:
        type: string

Fine grained annotations

Every json key can be mapped to an ontology term that will then be used as a predicate in the rdf data model. This allows developers of APIs to annotate complex json response/return types on the level of individual keys and thus at a much finer granularity onr:expects and orn:returns structures above.

Here inchi is a json key and is described in the JSON-LD definition with an ontology URI it will be automatically converted.

{"@context": {
    "@vocab": "http://openrisknet.org/schema#",
    "x-orn": "http://openrisknet.org/schema#",
    "x-orn-@id": "@id",
    "x-orn-@type":"@type",

    "smiles": "http://semanticscience.org/resource/CHEMINF_000018",
    "inchi": "http://semanticscience.org/resource/CHEMINF_000113",
    "inchikey": "http://semanticscience.org/resource/CHEMINF_000059",
    "cas": "http://semanticscience.org/resource/CHEMINF_000446"
  }
}

subject	predicate	object
_:b1	http://semanticscience.org/resource/CHEMINF_000113	_:b10
_:b10	http://openrisknet.org/schema#description	InChI String^^http://www.w3.org/2001/XMLSchema#string
_:b10	http://openrisknet.org/schema#in	path^^http://www.w3.org/2001/XMLSchema#string
_:b10	http://openrisknet.org/schema#name	InChI^^http://www.w3.org/2001/XMLSchema#string
_:b10	http://openrisknet.org/schema#required	true^^http://www.w3.org/2001/XMLSchema#boolean