3.5. Semantic API
This document describes the method and setting information for deploying Semantic API.
3.5.1. Overview
Semantic REST API, as a solution to improve accessibility between semantic and non-semantic environments. To achieve easier interpretation, eight basic functionalities along with their respective resource description has been defined for the retrieval and traversal of semantic data.
The “APIConfiguration.java” class contains one variable called “PREFIX_URI”, which defines the namespace URI to be used for defining all the concepts in the OWL Ontology model. This can be changed according to preference.
3.5.2. API Description
Following is the list of API functionalities and their brief description.
Table 1. API Functions
| # | Name | Description |
|---|---|---|
| 1. | Graph List | Get the list of graphs URI. Every set of graph data is stored in graphs, having unique graph URI. The ontologies are also stored as graphs in the TDB. This Request will get the list of those graphs URIs. |
| 2. | Entity List | Get the list of entity URIs where an entity can be one of following type: {Class, ObjectProperty, DataProperty, NamedIndividual, …} |
| 3. | Entity Info | Get the info of the given entity URI {Class, NamedIndividual, Object Property, Data Property}. i.e. Provide details of its type and properties {domains, ranges, subsumption, comment, …. } |
| 4. | Class -Hierarchy | Get the Class hierarchy of Class/Individual up to “n-level”, from child class to parent class. |
| 5. | Graph Info | Get the set of all triples of given graph URI. |
| 6. | Individual List | Get the URI list of all the Individuals of the given type. |
Table 2 describes the Request parameters for each API call.
Table 3-11 define the resource types. Here multiplicity defines the multiplicity of “values” of their properties. So, usually the properties having “List” can have the greater than 1 multiplicity.
Table 3. Resource description for sem:graphList
| property | datatype | multiplicity | Description |
|---|---|---|---|
| prefixList | sem:prefixListSimple or sem:prefixListNormal | 0..n | List of prefixes for the URIs / IRIs used in the resource. Format type can be suggested by the prefixFormat query parameter (allowed values: simple, normal) |
| graphList | URI | 0…n | List of graph URIs, starting with {prefix}, followed by : followed by graphID. |
Table 4. Resource description for sem:entityList
| property | datatype | multiplicity | Description |
|---|---|---|---|
| prefixList | sem:prefixListSimple or sem:prefixListNormal | 0..n | List of prefixes for the URIs / IRIs used in the resource. Format type can be suggested by the prefixFormat query parameter (allowed values: simple, normal) |
| entityList | URI | 0…n | List of entity URIs, starting with {prefix}, followed by : followed by entityID. |
Table 5. Resource description for sem:entityInfo
| property | datatype | multiplicity | Description |
|---|---|---|---|
| prefixList | sem:prefixListSimple or sem:prefixListNormal | 0..n | List of prefixes for the URIs / IRIs used in the resource. Format type can be suggested by the prefixFormat query parameter (allowed values: simple, normal) |
| entityDescription | sem:tripleInfoSimple or sem:tripleInfoNormal | 0…n | The value of this property will be the list of triples. Format type can be suggested by the descriptionFormat request parameter (allowed values: simple, normal) |
Table 6. Resrouce description for sem:graphInfo
| property | datatype | multiplicity | Description |
|---|---|---|---|
| prefixList | sem:prefixListSimple or sem:prefixListNormal | 0..n | List of prefixes for the URIs / IRIs used in the resource. Format type can be suggested by the prefixFormat query parameter (allowed values: simple, normal) |
| graphDescription | sem:tripleInfoNormal | 0…n | The value of this property will be the list of triples. Format type can be suggested by the descriptionFormat request parameter (allowed values: simple, normal) |
Table 7. Resource description for sem:individualList
| property | datatype | multiplicity | Description |
|---|---|---|---|
| prefixList | sem:prefixListSimple or sem:prefixListNormal | 0..n | List of prefixes for the URIs / IRIs used in the resource. Format type can be suggested by the prefixFormat request parameter (allowed values: simple, normal) |
| individualList | URI | 0…n | List of individual URIs, starting with {prefix}, followed by : followed by individualID. |
Table 8. Resource description for sem:prefixListSimple
| property | datatype | multiplicity | Description |
|---|---|---|---|
| {prefix} | URI | 1 | value for this property shall be the namespace IRI |
Table 9. Resource description for sem:prefixListNormal
| property | datatype | multiplicity | Description |
|---|---|---|---|
| prefix | string | 1 | value for this property shall prefix name |
| namespaceIRI | URI | 1 | value for this property shall be the namespace IRI |
Table 10. Resource description for sem:tripleInfoSimple
| property | datatype | multiplicity | Description |
|---|---|---|---|
| {predicate} | URI or plain literal or typed literal | 1…n | value for this property shall be a list of objects, defining different triples, having same subject and predicate. |
Table 11. Resource description for sem:tripleInfoNormal
| property | datatype | multiplicity | Description |
|---|---|---|---|
| subject | URI | 1 | value for this property shall subject of the triple. Value will start with {prefix}, followed by : followed by entityID. |
| predicate | URI | 1 | value for this property shall be the predicated or the triple Value will start with {prefix}, followed by : followed by entityID. |
| object | URI or plain literal or typed literal | 1 | Value for this property shall object of the triple. In case of URI, value will start with {prefix}, followed by : followed by entityID. |
3.5.3. API Usage Examples
Following tables 12-26 show the examples for each API call as well as their corresponding example responses. Table 29 shows the prefixes and their namespaces defined statically in the API. Currently, the API does not have the mechanism for managing prefixes, which is the scope for future work.
Table 12. Request example for API function 1. Graph List
| Request | |
|---|---|
| GET | http://www.city-hub.kr/semantics/v1/graphs?graphType=ontology&keyword=parking,air-quality&limit=10&prefixFormat=simple |
Table 13. Response example for API function 1. Graph List with resource sem:prefixListSimple
Table 14. Response example for API function 1. Graph List with resource sem:prefixListNormal
Table 15. Request example for API function 2. Entity List
| Request | |
|---|---|
| GET | http://www.city-hub.kr/semantics/v1/entities?keyword=parkinglot,parkingspot,longitude&entityType=owl:NamedIndividual,parking:ParkingLot,parking:ParkingSpot,owl:DatatypeProperty&limit=10 |
Table 16. Response example for API function 2. Entity List
Table 17. Request example for API function 3. Entity Info with responseType=normal
| Request | |
|---|---|
| GET | http://www.city-hub.kr/semantics/v1/entities/parking:ParkingLot_yt_lot_1&limit=100&rseponseType=normal |
Table 18. Response example for API function 3. Entity Info with resource sem:tripleInfoNormal
Table 19. Request example for API function 3. Entity Info with responseType=simple
| Request | |
|---|---|
| GET | http://www.city-hub.kr/semantics/v1/entities/parking:ParkingLot_yt_lot_1&limit=100&rseponseType=simple |
Table 20. Response example for API function 3. Entity Info with resource sem:tripleInfoSimple
Table 21. Request example for API function 4. Class Hierarchy
| Request | |
|---|---|
| GET | http://www.city-hub.kr/semantics/v1/classhierarchy/parking:ParkingLot&limit=100 |
Table 22. Response example for API function 4. Class Hierarchy
Table 23. Request example for API function 5. Graph Info
| Request | |
|---|---|
| GET | http://www.city-hub.kr/semantics/v1/graphs/parking:parkinglot_yt_lot_1?limit=100 |
Table 24. Response example for API function 5. Graph Info
Table 25. Request example for API function 6. Individual List
| Request | |
|---|---|
| GET | http://www.city-hub.kr/semantics/v1/individuals http://www.city-hub.kr/semantics/v1/individuals?classId=parking:Parkinglot, parking:ParkingSpot&limit=10 |
Table 26. Response example for API function 6. Individual List
Table 27. Predefined (static) prefix list in API
3.5.4 Pre-Installation
Semantic API is a Java Maven project, developed using Java Spring Boot. The project can be imported and executed in compatible java IDE such as Eclipse and IntelliJ. Following are the dependencies required for deployment.
3.5.4.1 Dependencies
- Minimum version of Java Required: 1.5.
- Maven Dependencies: These are listed under <dependencies> tab in “pom.xml”, in main project directory.
- spring-boot-starter-web (version 1.4.1)
- jakarta.xml.bind-api (version 2.3.2)
- jaxb-runtime (version 2.3.2)
- apache-jena-libs (version: 3.9.0)
- owlapi-distribution (version 5.1.16)
- json-simple (version 1.1.1)
- gson (version 2.8.6)
- External Jar Files: These files are not available in maven repository and may need to add in the build path manually. These can be found in project/lib/
- virt_jena3.jar
- virtjdbc4.jar
- Connection with Virtuoso Triple Store: Three parameters are required to connect to the virtuoso: host URL, user name and password.
- It is required that the triple store is already populated with ontologies (vocabularies), so that Semantic API can handle certain Requests, such as GET Class Hierarchy, appropriately.
- There are static number of prefixes defined in the API (can be found in PrefixRepository.java class). Any newly defined prefix should be added appropriately.
3.5.4.2 ServerConfiguration
- The file is located at project/src/java/com/cityhub/semantic/ServerConfiguration.java, where following parameters can be configured:
| Property | Sample | Description |
|---|---|---|
| API_BASE_URL | semantic/api/v1 | Parameter to set Semantic API's base URL. This can be changed based on preference |
| TDB_BASE_URL | jdbc:virtuoso://localhost:1111 | Parameter to set host URL. This default value is set for localhost. However it can be changed based on the specific ip address of the deployed TDB |
| TDB_USER | dba | Default user name for virtuoso TDB. However, different user can be provided if created in virtuoso with appropriate permissions. |
| TDB_PASS | dba | Default user password for virtuoso TDB. However, different user information can be provided if created in virtuoso with appropriate permissions. |
| ACP_BASE_URL | <must be defined> | This is the URL for the server handling Access Control Policy functions. There is no default value. It must be provided for proper Access Control Functionality. |
3.5.4.3 Important File Directories
- Following are the important directories for Semantic Validator.
- Project java code files : project/src/java/com/cityhub/semantic/
- External Jar files : project/lib
- Maven Dependencies : project/pom.xml
3.5.5 Deployment Steps
NOTE: the installation instructions are based on Eclipse IDE in Windows, so it may vary for different IDEs and platforms.
3.5.5.1 Download Project
Download the project from github and choose "semantic REST API"
3.5.5.2 Import Project in IDE
In Eclipse, Go to File>Import>Maven>Existing Maven Projects
Locate the downloaded project and import.
3.5.5.3 Add external Jar dependencies
- The external jars to be added are located in the project at project/lib. If they are not already added, then must be added manually.
- In Eclipse, right click on project folder, go to Build Path > Configure Build Path > Java Build Path. Then go under the Libraries tab, which shows the current jars added to the build path.
- On the right side click “Add External Jars”.
- Locate the lib directory and select the files inside.
- Click “Apply and Close”
3.5.5.4 Application Deployment
NOTE: The TDB and ACP Server must be running prior to the execution of this Application.
After all the required dependencies have been installed, the application can be executed using ServerApplication.java class located at project/src/java/com/cityhub/semantic/ServerApplication.java:
- Right click on ServerApplication.java, select "Run As", select either "Java Application" or "Spring Boot App".
- Upon execution, standard Spring Boot execution can be seen on the Eclipse Console.
- After the information is displayed: "...Started ServerApplication in 2.886 seconds ...", the console will stop displaying further information and the API is online to provide RESTful services.