Management API

REST API for managing ontologies in OntoPop.

Last updated: 01 March 2022Author: Jillur Quddus

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 method	POST
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.

Property	Description	Example
`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

Key	Value	Description
Content-Type	application/json	See request body above
X-API-Key	Issued API Key	See API Authentication for further details

Responses

HTTP Status	Description	Response Schema
201 Created	Ontology successfully created.	Ontology.class
401 Unauthorized	Creation of ontology unauthorized.	N/A
409 Conflict	Ontology 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 Error	Internal 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 method	GET
API endpoint	/management/ontologies

Path Variables

None

Request Body

Not applicable

Headers

Key	Value	Description
X-API-Key	Issued API Key	See API Authentication for further details

Responses

HTTP Status	Description	Response Schema
200 OK	Ontologies successfully retrieved.	Ontology.class
401 Unauthorized	Retrieval of ontologies unauthorized.	N/A
500 Internal Server Error	Internal 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 method	GET
API endpoint	/management/ontologies/{id}

Path Variables

Name	Description	Example
`id`	ID of the ontology to retrieve.	102

Request Body

Not applicable

Headers

Key	Value	Description
X-API-Key	Issued API Key	See API Authentication for further details

Responses

HTTP Status	Description	Response Schema
200 OK	Ontology successfully retrieved.	Ontology.class
401 Unauthorized	Retrieval of ontology unauthorized.	N/A
404 Not Found	Ontology not found.	N/A
500 Internal Server Error	Internal 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 method	PATCH
API endpoint	/management/ontologies/{id}

Path Variables

Name	Description	Example
`id`	ID of the ontology to update.	102

Request Body

Property	Description	Example
`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

Key	Value	Description
Content-Type	application/json	See request body above
X-API-Key	Issued API Key	See API Authentication for further details

Responses

HTTP Status	Description	Response Schema
200 OK	Ontology successfully updated.	Ontology.class
401 Unauthorized	Update of ontology unauthorized.	N/A
404 Not Found	Ontology not found.	N/A
500 Internal Server Error	Internal 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 method	PATCH
API endpoint	/management/ontologies/{id}/secrets

Path Variables

Name	Description	Example
`id`	ID of the ontology to update.	102

Request Body

Property	Description	Example
`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

Key	Value	Description
Content-Type	application/json	See request body above
X-API-Key	Issued API Key	See API Authentication for further details

Responses

HTTP Status	Description	Response Schema
200 OK	Ontology secrets successfully updated.	None
401 Unauthorized	Update of ontology unauthorized.	N/A
404 Not Found	Ontology not found.	N/A
500 Internal Server Error	Internal 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 method	DELETE
API endpoint	/management/ontologies/{id}

Path Variables

Name	Description	Example
`id`	ID of the ontology to delete.	102

Request Body

Not applicable

Headers

Key	Value	Description
Content-Type	application/json	See request body above
X-API-Key	Issued API Key	See API Authentication for further details

Responses

HTTP Status	Description	Response Schema
200 OK	Ontology successfully deleted.	None
401 Unauthorized	Deletion of ontology unauthorized.	N/A
404 Not Found	Ontology not found.	N/A
500 Internal Server Error	Internal server error.	N/A

Examples

Example request

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

Response (HTTP 200 OK)

Ontology successfully deleted.