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 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
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 (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
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 |
---|---|---|
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.