Management API

REST API for managing ontologies in OntoPop.

Please note that the OntoPop backend open-source software project, which includes the event-driven data pipelines and APIs, is undergoing extensive redesign and refactoring as part of OntoPop Community 3.x in order to improve performance, security, extensibility and maintainability. As a result, the documentation on this page will be significantly updated. Please refer to the OntoPop Roadmap for further information.

1. Monitor new ontology

Overview

Provide the details of a new W3C Web Ontology Language (OWL) ontology that OntoPop should monitor for changes.

HTTP request methodPOST
API endpoint/management/ontologies

Path Variables

None

Request Body

Please note that OntoPop Community 2.x only supports GitHub repositories (public and private). Please refer to the Compatibility Matrix for a full list of software services and vendors supported by OntoPop.

PropertyDescriptionExample
name (string) *Short free-text name of the ontology (required).National Highways Corporate Ontology
description (string)Free-text description of the ontology (optional)National Highways conceptual data model/td>
repoUrl (string) *URL of the Git repository where the OWL file for this ontology is managed (required).https://github.com/myorg/myrepo
repoName (string) *The name of the Git repository where the OWL file for this ontology is managed (required).myrepo
repoOwner (string) *The owner of the Git repository where the OWL file for this ontology is managed (required).myorg
repoPrivate (boolean) *Whether the Git repository where the OWL file for this ontology is managed is a private repository (required).true
repoResourcePath (string) *The path to the OWL file for this ontology inside the Git repository (required).data/ontology.owl
repoBranch (string) *The name of the branch in the Git repository where the OWL file for this ontology is managed (required).develop
repoToken (string)If the Git repository is private, please provide an access token that will be used to both download and commit changes to the OWL file. Consequently this access token should have both read and write privileges provisioned to it (optional).ghp_123456789abcdef
repoWebhookSecret (string) *The custom webhook secret defined when configuring the webhook for the Git repository (required).mysecret123
webProtegeProjectId (string)If the ontology is being actively developed in WebProtege, please provide the WebProtege project ID. This will be used to consume WebProtege webhooks and push changes from WebProtege to OntoPop in real-time (optional).0b3be685-73bd-4d5a-b866-e70d0ac7269b

Headers

KeyValueDescription
Content-Typeapplication/jsonSee request body above
X-API-KeyIssued API KeySee API Authentication for further details

Responses

HTTP StatusDescriptionResponse Schema
201 CreatedOntology successfully created.Ontology.class
401 UnauthorizedCreation of ontology unauthorized.N/A
409 ConflictOntology already exists (i.e. an ontology with the same repository URL, resource path and branch is already being monitored by OntoPop).N/A
500 Internal Server ErrorInternal server error.N/A

Examples

Example request

{
    "name": "National Highways Corporate Ontology", 
    "description": "National Highways conceptual data model", 
    "repoUrl": "https://github.com/myorg/myrepo", 
    "repoName": "myrepo", 
    "repoOwner": "myorg", 
    "repoPrivate": true, 
    "repoResourcePath": "data/ontology.owl",
    "repoBranch": "develop", 
    "repoToken": "ghp_123456789abcdef",  
    "repoWebhookSecret": "mysecret123", 
    "webProtegeProjectId": "0b3be685-73bd-4d5a-b866-e70d0ac7269b"
}

Response (HTTP 201 Created)

{
    "id": 103,
    "name": "National Highways Corporate Ontology",
    "description": "National Highways conceptual data model",
    "repoUrl": "https://github.com/myorg/myrepo",
    "repoName": "myrepo",
    "repoOwner": "myorg",
    "repoPrivate": true,
    "repoResourcePath": "data/ontology.owl",
    "repoBranch": "develop",
    "dateCreated": "2022-02-18 12:33:04",
    "dateLastUpdated": "2022-02-18 12:33:04",
    "webProtegeProjectId": "0b3be685-73bd-4d5a-b866-e70d0ac7269b"
}

2. Get all ontologies

Overview

Get all the W3C Web Ontology Language (OWL) ontologies that OntoPop is monitoring for changes.

HTTP request methodGET
API endpoint/management/ontologies

Path Variables

None

Request Body

Not applicable

Headers

KeyValueDescription
X-API-KeyIssued API KeySee API Authentication for further details

Responses

HTTP StatusDescriptionResponse Schema
200 OKOntologies successfully retrieved.Ontology.class
401 UnauthorizedRetrieval of ontologies unauthorized.N/A
500 Internal Server ErrorInternal server error.N/A

Examples

Example response (HTTP 200 OK)

[
    {
        "id": 102,
        "name": "Star Wars Universe",
        "description": "Star Wars Universe",
        "repoUrl": "https://github.com/myorg/myrepo",
        "repoName": "myrepo",
        "repoOwner": "myorg",
        "repoPrivate": true,
        "repoResourcePath": "data/star-wars-ontology.owl",
        "repoBranch": "develop",
        "dateCreated": "2022-01-16 12:30:00",
        "dateLastUpdated": "2022-01-16 12:30:00",
        "webProtegeProjectId": "6g4hj987-99bd-3w8a-b899-e80d0ac7277d"
    }, 
    {
        "id": 103,
        "name": "National Highways Corporate Ontology",
        "description": "National Highways conceptual data model",
        "repoUrl": "https://github.com/myorg/myrepo",
        "repoName": "myrepo",
        "repoOwner": "myorg",
        "repoPrivate": true,
        "repoResourcePath": "data/ontology.owl",
        "repoBranch": "develop",
        "dateCreated": "2022-02-18 12:33:04",
        "dateLastUpdated": "2022-02-18 12:33:04",
        "webProtegeProjectId": "0b3be685-73bd-4d5a-b866-e70d0ac7269b"
    }

    ...

]

3. Get ontology

Overview

Get a specific W3C Web Ontology Language (OWL) ontology that OntoPop is monitoring for changes.

HTTP request methodGET
API endpoint/management/ontologies/{id}

Path Variables

NameDescriptionExample
idID of the ontology to retrieve.102

Request Body

Not applicable

Headers

KeyValueDescription
X-API-KeyIssued API KeySee API Authentication for further details

Responses

HTTP StatusDescriptionResponse Schema
200 OKOntology successfully retrieved.Ontology.class
401 UnauthorizedRetrieval of ontology unauthorized.N/A
404 Not FoundOntology not found.N/A
500 Internal Server ErrorInternal server error.N/A

Examples

Example request

$ curl -X GET http://localhost:8080/management/ontologies/102

Response (HTTP 200 OK)

{
    "id": 102,
    "name": "Star Wars Universe",
    "description": "Star Wars Universe",
    "repoUrl": "https://github.com/myorg/myrepo",
    "repoName": "myrepo",
    "repoOwner": "myorg",
    "repoPrivate": true,
    "repoResourcePath": "data/star-wars-ontology.owl",
    "repoBranch": "develop",
    "dateCreated": "2022-01-16 12:30:00",
    "dateLastUpdated": "2022-01-16 12:30:00",
    "webProtegeProjectId": "6g4hj987-99bd-3w8a-b899-e80d0ac7277d"
}

4. Update ontology

Overview

Update the non-sensitive attributes of an existing W3C Web Ontology Language (OWL) ontology that OntoPop is monitoring for changes.

HTTP request methodPATCH
API endpoint/management/ontologies/{id}

Path Variables

NameDescriptionExample
idID of the ontology to update.102

Request Body

Please note that OntoPop Community 2.x only supports GitHub repositories (public and private). Please refer to the Compatibility Matrix for a full list of software services and vendors supported by OntoPop.

PropertyDescriptionExample
name (string)Short free-text name of the ontology (optional).National Highways Corporate Ontology
description (string)Free-text description of the ontology (optional)National Highways conceptual data model/td>
repoUrl (string)URL of the Git repository where the OWL file for this ontology is managed (optional).https://github.com/myorg/myrepo
repoName (string)The name of the Git repository where the OWL file for this ontology is managed (optional).myrepo
repoOwner (string)The owner of the Git repository where the OWL file for this ontology is managed (optional).myorg
repoPrivate (boolean)Whether the Git repository where the OWL file for this ontology is managed is a private repository (optional).true
repoResourcePath (string)The path to the OWL file for this ontology inside the Git repository (optional).data/ontology.owl
repoBranch (string)The name of the branch in the Git repository where the OWL file for this ontology is managed (optional).develop
webProtegeProjectId (string)If the ontology is being actively developed in WebProtege, please provide the WebProtege project ID. This will be used to consume WebProtege webhooks and push changes from WebProtege to OntoPop in real-time (optional).0b3be685-73bd-4d5a-b866-e70d0ac7269b

Headers

KeyValueDescription
Content-Typeapplication/jsonSee request body above
X-API-KeyIssued API KeySee API Authentication for further details

Responses

HTTP StatusDescriptionResponse Schema
200 OKOntology successfully updated.Ontology.class
401 UnauthorizedUpdate of ontology unauthorized.N/A
404 Not FoundOntology not found.N/A
500 Internal Server ErrorInternal server error.N/A

Examples

Example request

$ curl -X PATCH http://localhost:8080/management/ontologies/102
   -H 'Content-Type: application/json'
   -d '{ "name": "Star Wars", "description": "The Star Wars Universe modelled using an ontology", "repoBranch": "main" }'

Response (HTTP OK 200)

{
    "id": 102,
    "name": "Star Wars",
    "description": "The Star Wars Universe modelled using an ontology",
    "repoUrl": "https://github.com/myorg/myrepo",
    "repoName": "myrepo",
    "repoOwner": "myorg",
    "repoPrivate": true,
    "repoResourcePath": "data/star-wars-ontology.owl",
    "repoBranch": "main",
    "dateCreated": "2022-01-16 12:30:00",
    "dateLastUpdated": "2022-01-18 13:15:00",
    "webProtegeProjectId": "6g4hj987-99bd-3w8a-b899-e80d0ac7277d"
}

5. Update ontology secrets

Overview

Update the secret attributes of an existing W3C Web Ontology Language (OWL) ontology that OntoPop is monitoring for changes.

HTTP request methodPATCH
API endpoint/management/ontologies/{id}/secrets

Path Variables

NameDescriptionExample
idID of the ontology to update.102

Request Body

Please note that OntoPop Community 2.x only supports GitHub repositories (public and private). Please refer to the Compatibility Matrix for a full list of software services and vendors supported by OntoPop.

PropertyDescriptionExample
repoToken (string)If the Git repository is private, the updated access token that will be used to both download and commit changes to the OWL file. Consequently this access token should have both read and write privileges provisioned to it (optional).ghp_123456789abcdef
repoWebhookSecret (string)The updated custom webhook secret defined when updating the webhook for the Git repository (optional).mysecret123

Headers

KeyValueDescription
Content-Typeapplication/jsonSee request body above
X-API-KeyIssued API KeySee API Authentication for further details

Responses

HTTP StatusDescriptionResponse Schema
200 OKOntology secrets successfully updated.None
401 UnauthorizedUpdate of ontology unauthorized.N/A
404 Not FoundOntology not found.N/A
500 Internal Server ErrorInternal server error.N/A

Examples

Example request

$ curl -X PATCH http://localhost:8080/management/ontologies/102/secrets
   -H 'Content-Type: application/json'
   -d '{ "repoToken": "ghp_9a8b7c6d5e4f" }'

Response (HTTP 200 OK)

Ontology secrets successfully updated.

6. Delete ontology

Overview

Delete a specific W3C Web Ontology Language (OWL) ontology that OntoPop is monitoring for changes.

HTTP request methodDELETE
API endpoint/management/ontologies/{id}

Path Variables

NameDescriptionExample
idID of the ontology to delete.102

Request Body

Not applicable

Headers

KeyValueDescription
Content-Typeapplication/jsonSee request body above
X-API-KeyIssued API KeySee API Authentication for further details

Responses

HTTP StatusDescriptionResponse Schema
200 OKOntology successfully deleted.None
401 UnauthorizedDeletion of ontology unauthorized.N/A
404 Not FoundOntology not found.N/A
500 Internal Server ErrorInternal server error.N/A

Examples

Example request

$ curl -X DELETE http://localhost:8080/management/ontologies/102

Response (HTTP 200 OK)

Ontology successfully deleted.