OntoPop
Search…
Management API
REST API for managing OntoPop ontologies.
Last Updated: 01 March 2022 • Page Author: Jillur Quddus

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 version 2.x currently only supports GitHub repositories (public and private). Please refer to the Compatibility Matrix for a full list of software services 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.
repoUrl (string) *
URL to 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.
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.
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.
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

Please note that OntoPop version 2.x currently only supports GitHub repositories (public and private). Please refer to the Compatibility Matrix for a full list of software services supported by OntoPop.
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.
repoUrl (string)
URL to 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
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.
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

Please note that OntoPop version 2.x currently only supports GitHub repositories (public and private). Please refer to the Compatibility Matrix for a full list of software services supported by OntoPop.
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.