In this presentation we describe the Ontology-Based APIs framework (OBA), our approach to automatically create REST APIs from ontologies while following RESTful API best practices. Given an ontology (or ontology network) OBA uses standard technologies familiar to web developers (OpenAPI Specification, JSON) and combines them with W3C standards (OWL, JSON-LD frames and SPARQL) to create maintainable APIs with documentation, units tests, automated validation of resources and clients (in Python, Javascript, etc.) for non Semantic Web experts to access the contents of a target knowledge graph. We showcase OBA with three examples that illustrate the capabilities of the framework for different ontologies.

1. Information Sciences Institute
OBA: An Ontology-Based Framework for
Creating REST APIs for Knowledge Graphs
Daniel Garijo and Maximiliano Osorio
{dgarijo,mosorio}@isi.edu
@dgarijov, @SirSpock

2. Information Sciences Institute
Exploring a SPARQL endpoint
LOV
https://lists.w3.org/Archives/Public/semantic-web/2015Jan/0087.html
W3C Semantic Web lists (2015)
Get all classes
Get
documentation
and examples
Get all classes
and
properties
Luca Matteis
Thomas Francart
Jerven Bolleman

3. Information Sciences Institute
Requirements for KG consumption
LOV
https://lod-cloud.net/#diagram
SPARQL endpoint
Ontology/vocabulary
Documentation/
examples
Developer

4. Information Sciences Institute
The gap between KG engineers and
consumers
Ontology/KG engineer
- Familiar with
ontologies/vocabularies used to
represent data
- Exposes data in SPARQL
endpoint/RDF dump
- Knows SPARQL queries
Web developer
- Unfamiliar with
ontologies/vocabularies used
- Uses JSON to read and
manipulate data
- Uses REST APIs to retrieve
data

5. Information Sciences Institute
OBA: Ontology Based APIs
OWL
Ontology
SPARQL
endpoint
OpenAPI
Specification
(OAS)
REST API
Server

6. Information Sciences Institute
OBA: Ontology Based APIs
OWL
Ontology
SPARQL
endpoint
OpenAPI
Specification
(OAS)
REST API
Server
OWL to OAS
Mapping
Generate and
test server
Automated
JSON to
RDF
handling
Generate
clients

7. Information Sciences Institute
OBA: Ontology Based APIs
OWL
Ontology
SPARQL
endpoint
OpenAPI
Specification
(OAS)
REST API
Server
OWL to OAS
Mapping
Generate and
test server
Automated
JSON to
RDF
handling
Generate
clients

8. Information Sciences Institute
Mapping OWL to OAS
OpenAPI specification (https://swagger.io/specification/)
• Each class maps to an OAS “schema”
– Mapping covers classes, subclasses, properties, data properties,
domain, ranges, and some OWL constraints*
– You can filter undesired paths
• Each class has two path for GET:
– /{ClassName}
– /{ClassName}/{instanceID}
• One path for PUT, POST and DELETE:
– /{ClassName} [POST]
– /{ClassName}/{instanceID} [PUT, DELETE]
*More information: https://oba.readthedocs.io/en/latest/mapping/

9. Information Sciences Institute
Mapping OWL to OAS: Example
Person
Student
Student
Record
subclassOf
hasRecord
:Person rdf:type owl:Class ;
rdfs:label "Person"@en.
:Student rdf:type owl:Class ;
rdfs:subClassOf :Person ;
rdfs:label "Student"@en .
:hasRecord rdf:type owl:ObjectProperty
, owl:FunctionalProperty ;
rdfs:domain :Student ;
rdfs:range :StudentRecord ;
rdfs:label "has record"@en .
components:
schemas:
Person:
type: object
properties:
name:
type: string
Student:
allOf:
- $ref: '#/components/schemas/Person'
- type: object
properties:
hasRecord:
items:
$ref: '#/components/schemas/StudentRecord
type: array
maxItems: 1
OWL (ttl) OAS (yaml)

10. Information Sciences Institute
OBA: Ontology Based APIs
OWL
Ontology
SPARQL
endpoint
OpenAPI
Specification
(OAS)
REST API
Server
OWL to OAS
Mapping
Generate and
test server
Automated
JSON to
RDF
handling
Generate
clients

11. Information Sciences Institute
Generating the server: Workflow
OpenAPITools / openapi-generator
stain / owl2jsonld

12. Information Sciences Institute
OBA: Ontology Based APIs
OWL
Ontology
SPARQL
endpoint
OpenAPI
Specification
(OAS)
REST API
Server
OWL to OAS
Mapping
Generate and
test server
Automated
JSON to
RDF
handling
Generate
clients

13. Information Sciences Institute
From RDF to JSON
https://w3c.github.io/json-ld-framing/

14. Information Sciences Institute
Custom Queries
Additional queries may be required in the API
1. Create a new query
– CONSTRUCT
1. Define query parameters
– Basil’s convention
1. Add path to OAS
Basil
custom_paths:
/custom/models/variable:
get:
description: Get models by variable name
parameters:
- description: Name of the custom query
in: query
name: custom_query_name
required: false
schema:
default: custom_models_variable
type: string
- description: variable to search
in: query
name: label
required: true
schema:
type: string
responses:
200:
content:
application/json:
...

15. Information Sciences Institute
OBA: Ontology Based APIs
OWL
Ontology
SPARQL
endpoint
OpenAPI
Specification
(OAS)
REST API
Server
OWL to OAS
Mapping
Generate and
test server
Automated
JSON to
RDF
handling
Generate
clients

16. Information Sciences Institute
Generating your own client
Example: https://model-catalog-python-api-client.readthedocs.io/en/latest/models/
...

17. Information Sciences Institute
Performance
150 ms (max) of delay
60 req/sec (With reverse proxy
caching enabled)

18. Information Sciences Institute
Conclusions and Future Work
Using SPARQL endpoints as a non Semantic Web expert is
challenging
- Need to know SPARQL
- Need to understand the ontologies used to represent the data
- Need to understand documentation and examples
OBA enables KG engineers to easily expose REST APIs from
their ontologies/vocabularies:
- Create an OAS specification from an ontology
- Generate a REST server that accepts and returns JSON following the OAS
- Generate tests
Next for OBA: JSON-LD, GraphQL support, advanced SHACL validation

19. Information Sciences Institute
Help us improve OBA
Documentation:
https://oba.readthedocs.io/en/latest/
GitHub:
https://github.com/KnowledgeCaptureAndDiscovery/OBA/
Examples:
https://oba.readthedocs.io/en/latest/examples/
OWL
SPARQL
JSON-LD
OpenAPI +
documentation
REST
JSON

20. Information Sciences Institute
Acknowledgements
Yolanda Gil
Hernan Vargas
Oscar Corcho
Paola Espinoza
Carlos Badenes
Karl Hammar
Anonymous ISWC reviewers
This work was funded by the Defense Advanced Research Projects Agency with award
W911NF-18-1-0027 and the National Science Foundation with award ICER-144032

21. Information Sciences Institute
OBA: An Ontology-Based Framework for
Creating REST APIs for Knowledge Graphs
Daniel Garijo and Maximiliano Osorio
dgarijo@isi.edu
@dgarijov