Page Comparison

...

This documentation provides a step-by-step guide to creating REST APIs for managing CRUD operations for each class using SPARQL templates on the ENAPSO together free platform. By following these instructions, you will be able to automate and enhance the interactivity of your Knowledge Graph through RESTful services.

Why Use Multiple REST Endpoints?

Accessing EBUCorePlus knowledge graphs via multiple REST endpoints, as opposed to a central SPARQL template endpoint, offers several key advantages

REST Compliance

Standardized Methods: RESTful services use standard HTTP methods (GET, POST, PUT, DELETE) to perform CRUD operations. This makes the API intuitive and easier to use, as developers are already familiar with these methods.
Statelessness: RESTful APIs are stateless, meaning each request from a client contains all the information needed to process the request. This simplifies the server design and improves scalability.

Security

Granular Access Control: Each REST endpoint can be individually secured, allowing you to enforce specific access permissions for different operations. This granular control helps prevent unauthorized access to sensitive data and ensures that only authorized users can perform certain actions.
Reduced Attack Surface: By distributing functionality across multiple endpoints, you limit the impact of potential security vulnerabilities. If one endpoint is compromised, it does not necessarily expose the entire system, enhancing overall security.

Scalability

Load Distribution: With multiple endpoints, you can distribute the load more effectively. Different endpoints can be scaled independently based on demand, leading to better performance and resource utilization.

Access the Swagger Documentation

Navigate to the View Management Service documentation in your web browser. This interface provides access to all the necessary endpoints for managing and executing SPARQL templates.

...

Find the create-endpoint-4-template endpoint, which is used for setting up new REST APIs for each SPARQL template.
Click on the "Try it out" button to enable interactive usage of this endpoint.

Configure the Endpoint Details

In the records array, you will configure each CRUD operation as a separate object. Here’s how you can set up each endpoint for the EditorialObject class:

Code Block

language	json

{
    "records": [
        {
            "endpoint": "editorialObject",
            "baseURL": "/v1",
            "endpointConfig": [
                {
                    "method": "get",
                    "template": "readEditorialObject"
                },
                {
                    "method": "post",
                    "template": "createEditorialObject"
                },
                {
                    "method": "put",
                    "template": "updateEditorialObject"
                },
                {
                    "method": "delete",
                    "template": "deleteEditorialObject"
                }
            ]
        }
    ]
}

Variable Descriptions
- records: This array holds one or more configuration objects. Each object defines a set of CRUD operations associated with a specific endpoint.
  - endpoint: This string specifies the name of the endpoint. It acts as a part of the URL path where the API will be accessible. For example, "editorialObject" results in a REST endpoint that could be accessed via ${baseURL}/editorialObject.
  - baseURL: This is the base path under which the endpoint will be grouped. For instance, "/v1" indicates that the endpoint will be accessed under the version 1 group, forming part of the complete URL path. For example, http://localhost/enapso-dev/view-management${baseURL}/${endpoint} will become http://localhost/enapso-dev/view-management/v1/editorialObject.
  - endpointConfig: An array of objects where each object specifies a CRUD operation and the associated settings:
    - method: The HTTP method (e.g., "get", "post", "put", "delete") that determines what kind of operation this endpoint will perform. This corresponds to the CRUD operation:
      - "get" for reading or retrieving data,
      - "post" for creating new data,
      - "put" for updating existing data,
      - "delete" for removing data.
    - template: The name of the SPARQL template that will be executed when this endpoint is called. It ties the REST API directly to a predefined SPARQL operation within the database management system.

After entering all the necessary details, click on the "Execute" button. A successful request will create REST endpoints for each configured operation.
The response will indicate success, confirming that the endpoints are now set up and ready for use.

...

To retrieve information of EditorialObject instances, use the following curl command to send a GETrequest

Basic GET Request

To retrieve information about EditorialObject instances, you can use the following curl command:

Code Block

language	sh

curl -X GET http://localhost/enapso-dev/view-management/v1/editorialObject

...

Passing Filters

You can pass filters using the filter.propertyName=value format in the query parameters. For example, if the property IRI is http://www.ebu.ch/metadata/ontologies/ebucoreplus#title, you will use the property name title after the hash.

Since the ebucoreplus ontology primarily involves parent-to-child relationships, most filters will be based on these relationships. However, if you want to filter based on child-to-parent relationships, you can also do that. For this, you need to pass the property name with the complete IRI enclosed in angle brackets (<>). The filter will be applied accordingly.

Example

1. Filtering by a Property

To filter EditorialObject instances where the property titleis Das Boot, you would use:

Code Block

language	sh

curl -X GET "http://localhost/enapso-dev/view-management/v1/editorialObject?filter.title=Das%20Boot"

...

2. Filtering by a Property with a Full IRI (Child to Parent)

In ebucorepus ontologies, relationships are defined from a parent entity to a child entity. However, there are cases where we need to filter entities based on relationships defined in the opposite direction, i.e., from child to parent. This is known as a child-to-parent relationship.

In such scenarios, we apply filters based on the property defined in the child entity that points to the parent entity. To do this, we use the full IRI (Internationalized Resource Identifier) of the property and the specific IRI of the child entity we are interested in. By doing so, we can retrieve all parent entities that are connected to the specified child entity through the defined relationship.

Example of Child-to-Parent Relationship

Let's consider a practical example using an ontology for EditorialObjects and Assets.

In ebucorepus ontology:

An Asset has a property hasRelatedEditorialObject that links to EditorialObject.

Objective

We want to retrieve all EditorialObjects that are related to a specific Asset.

Steps

Identify the property IRI that defines the relationship from the Asset to the EditorialObject. In this case, it is http://www.ebu.ch/metadata/ontologies/ebucoreplus#hasRelatedEditorialObject.
Pass the full IRI of this property along with the IRI of the specific Asset we are interested in.

Example

To filter EditorialObject instances based on a relationship property (child-to-parent) that requires the full IRI of the property, such as <http://www.ebu.ch/metadata/ontologies/ebucoreplus#hasRelatedEditorialObject> you would use

Code Block

language	sh

curl -X GET "http://localhost/enapso-dev/view-management/v1/editorialObject?filter.%3Chttp%3A%2F%2Fwww.ebu.ch%2Fmetadata%2Fontologies%2Febucoreplus%23hasRelatedEditorialObject%3E=http%3A%2F%2Fwww.ebu.ch%2Fmetadata%2Fontologies%2Febucoreplus%2Fdata%2FAsset_37f6d90c-87c9-4c1f-9a46-ff1102f9bd8a"

...

Important Notes

Encoding URIs: When passing any value, ensure it is URL-encoded.

Detailed Example with Multiple Filters

Suppose you want to filter EditorialObject instances where:

The property title is Run Lola Run.
The child-to-parent (Asset to EditorialObject) property <http://www.ebu.ch/metadata/ontologies/ebucoreplus#hasRelatedEditorialObject> is http://www.ebu.ch/metadata/ontologies/ebucoreplus/data/Asset_37f6d90c-87c9-4c1f-9a46-ff1102f9bd8a.

Code Block

language	bash

curl -X GET "http://localhost/enapso-dev/view-management/v1/editorialObject

...

?filter.%3Chttp%3A%2F%2Fwww.ebu.ch%2Fmetadata%2Fontologies%2Febucoreplus%23hasRelatedEditorialObject%3E=http%3A%2F%2Fwww.ebu.ch%2Fmetadata%2Fontologies%2Febucoreplus%2Fdata%2FAsset_37f6d90c-87c9-4c1f-9a46-ff1102f9bd8a&filter.title=Run%20Lola%20Run"

...

3. Update (PUT)

To update an existing EditorialObject, use the following curl command to send a PUT request with the IRI and new values:

...

Versions Compared

Old Version 5

New Version 6

Key

Why Use Multiple REST Endpoints?

REST Compliance

Security

Scalability

Access the Swagger Documentation

Basic GET Request

Passing Filters

Example

1. Filtering by a Property

2. Filtering by a Property with a Full IRI (Child to Parent)

Example

Important Notes

Detailed Example with Multiple Filters

3. Update (PUT)