...
Standardized Methods: RESTful services use standard HTTP methods (GET, POST, PUTPATCH, 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.
...
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.
Accurately Validating Input Parameters: By distributing functionality across multiple endpoints, you enhance the accuracy of input parameter validation. This approach minimizes the risk of improper data handling and helps maintain the integrity of the system, even if one endpoint encounters issues.
...
Endpoint
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.
...
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 theEditorialObject
class:. You can copy and paste the following snippet into your post body as it creates the CRUD endpoint for theEditorialObject
class.Code Block language json { "records": [ { "endpoint": "editorialObject", "baseURL": "/v1", "endpointConfig": [ { "method": "get", "template": "readEditorialObject" }, { "method": "post", "template": "createEditorialObject" }, { "method": "patch", "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 becomehttp://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
patch
,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
patch
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.
...
Find the
delete-endpoint-of-template
endpoint, which is used for removing existing REST APIs of 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 remove REST endpoints of theEditorialObject
class:Code Block { "records": [ { "endpoint": "editorialObject", "baseURL": "/v1", "endpointConfig": [ { "method": "get", "template": "readEditorialObject" }, { "method": "post", "template": "createEditorialObject" }, { "method": "patch", "template": "updateEditorialObject" }, { "method": "delete", "template": "deleteEditorialObject" } ] } ] }
Variable Descriptions
records: This array holds one or more configuration objects.
endpoint: This string specifies the name of the endpoint. It acts as a part of the URL path where the API is 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 is grouped. For instance, "/v1" indicates that the endpoint is to 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 template that needs to be removed.
method: The HTTP method (e.g., "
get
", "post
", "put"patch
, "delete
") that determines what kind of operation needs to be removed. This corresponds to the CRUD operation:get
for reading or retrieving data,post
for creating new data,put
patch
for updating existing data,delete
for removing data.
template: The name of the SPARQL template as we create one method for each template name which is called when we send a request on that REST method so as to remove that method.
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 removed.
...
To create a new EditorialObject
, use the following curl
command to class instance, send a POST request :
Code Block | ||
---|---|---|
| ||
curl -X POST "http://localhost/enapso-dev/view-management/v1/editorialObject" -H "Content-Type: application/json" -d "{\"variables\": {\"iri\": \"http://ont.enapso.com/sparql-template#EditorialObject_2f9b1462-e937-4416-8c23-ce96fc42dc55\", \"title\": \"Never Look Away\", \"shotLog\": \"Visual storytelling that captures the protagonist artistic journey and the tumultuous history of Germany.\"}}" |
...
This command sends the data to create a new instance of an EditorialObject
.
2. Read (GET)
To retrieve information of EditorialObject
instances, use the following curl
command to send a GET
request
Basic GET Request
To retrieve information about EditorialObject
instances, you can use the following curl command:
...
language | sh |
---|
...
using the following curl command. Ensure that the namedGraph
key and value (namedGraph specifies the graph in the triplestore where your information is preserved), are included in the POST body with the information you want to create. Passing the namedGraph
is necessary when using ENAPSO together with the free version.
You can include an optional namespace variable, which is used to create a unique iri
by attaching it to the iri
before the UUID. If you pass both namespace
and iri
in the variables
object, it will use the iri
you provide. If you pass only the namespace
and not iri
, the iri
will be generated using the namespace.
If you do not pass either iri
or namespace
, it will use the default namespace
(http://ont.enapso.com/dotnetpro#
)and create the iri.
The namespace
should end with a separator # or /, with # being the more practical choice.
Code Block | ||
---|---|---|
| ||
curl -X POST "http://localhost/enapso-dev/view-management/v1/editorialObject |
...
Passing Limit and Offset Parameters
To retrieve information about EditorialObject
instances with limit and offset parameters, The limit
parameter specifies the maximum number of results to return, while the offset
parameter specifies the starting point in the list of results, effectively skipping the first offset
number of results. you can use the following curl command:
Code Block |
---|
curl --get "http://localhost/enapso-dev/view-management/v1/editorialObject?limit=10&offset=10" |
Passing Filters
...
" -H "Content-Type: application/json" -d "{\"namedGraph\": \"http://www.ebu.ch/metadata/ontologies/ebucoreplus/demodata\",\"namespace\": \"http://www.ebu.ch/metadata/ontologies |
...
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.
1. Filtering by a Property
...
/ebucoreplus/demodata#\",\"variables\": {\"iri\": \"http://ont.enapso.com/sparql-template#EditorialObject_2f9b1462-e937-4416-8c23-ce96fc42dc55\", \"title\": \"Never Look Away\", \"shotLog\": \"Visual storytelling that captures the protagonist artistic journey and the tumultuous history of Germany.\"}}" |
...
This command sends the data to create a new instance of an EditorialObject
.
2. Read (GET)
To retrieve information of EditorialObject
instances, use the following curl
command to send a GET
request
Basic GET Request
To retrieve information about EditorialObject
instances, you can use the following curl command:
Code Block | ||
---|---|---|
| ||
curl --getX GET "http://localhost/enapso-dev/view-management/v1/editorialObject" --data-urlencode "filter.title=Das Boot" |
...
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 propertyhasRelatedEditorialObject
that links toEditorialObject
.
Objective
We want to retrieve all EditorialObjects
that are related to a specific Asset
.
Steps
...
...
Passing Limit and Offset Parameters
To retrieve information about EditorialObject
instances with limit
and offset
parameters, The limit
parameter specifies the maximum number of results to return, while the offset
parameter specifies the starting point in the list of results, effectively skipping the first offset
number of results. you can use the following curl command:
Code Block |
---|
curl --get "http://localhost/enapso-dev/view-management/v1/editorialObject?limit=10&offset=10" |
...
Passing namedGraph Parameters
To retrieve information about EditorialObject
instances with namedGraph
parameters, The namedGraph
parameter retrieves the class instances from a specific namedGraph
of the graph database repository. you can use the following curl command:
Code Block |
---|
curl --get "http://localhost/enapso-dev/view-management/v1/editorialObject" --data-urlencode "namedGraph=http://www.ebu.ch/metadata/ontologies |
...
Pass the full IRI
of this property along with the IRI
of the specific Asset
we are interested in.
Example
...
/ebucoreplus/demodata" |
...
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#hasRelatedEditorialObject>ebucoreplus#title
, you would use
Code Block | ||
---|---|---|
| ||
curl --get "http://localhost/enapso-dev/view-management/v1/editorialObject" --data-urlencode "filter.%3Chttp%3A%2F%2Fwww.ebu.ch%2Fmetadata%2Fontologies%2Febucoreplus%23hasRelatedEditorialObject%3E=http://www.ebu.ch/metadata/ontologies/ebucoreplus/data/Asset_37f6d90c-87c9-4c1f-9a46-ff1102f9bd8a" |
...
Important Notes
Encoding URIs: When passing property
IRI
, ensure it is URL-encoded.
3. Detailed Example with Multiple Filters
Suppose you want to filter EditorialObject
instances where:
The property
title
isRun Lola Run
.The
child-to-parent
(Asset
toEditorialObject
) property<http://www.ebu.ch/metadata/ontologies/ebucoreplus#hasRelatedEditorialObject>
ishttp://www.ebu.ch/metadata/ontologies/ebucoreplus/data/Asset_37f6d90c-87c9-4c1f-9a46-ff1102f9bd8a
.
...
language | bash |
---|
...
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.
1. Filtering by a Property
To filter EditorialObject
instances where the property title
is Das Boot
, you would use:
Code Block | ||
---|---|---|
| ||
curl --get "http://localhost/enapso-dev/view-management/v1/editorialObject" --data-urlencode "filter.title=Das Boot" |
...
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 propertyhasRelatedEditorialObject
that links toEditorialObject
.
Objective
We want to retrieve all EditorialObjects
that are related to a specific Asset
.
Steps
Identify the property
IRI
that defines the relationship from theAsset
to theEditorialObject
. In this case, it ishttp://www.ebu.ch/metadata/ontologies/
...
3. Update (PATCH)
...
ebucoreplus#hasRelatedEditorialObject
.Pass the full
IRI
of this property along with theIRI
of the specificAsset
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 | ||
---|---|---|
| ||
curl --X PUTget "http://localhost/enapso-dev/view-management/v1/editorialObject" -H "Content-Type: application/json" -d "{\"variables\": {\"iri\": \"http://ont.enapso.com/sparql-template#EditorialObject_2f9b1462-e937-4416-8c23-ce96fc42dc55\", \"productionSynopsis\": \"Directed by Florian Henckel von Donnersmarck, this sweeping historical drama delves into themes of art, love, tragedy, and the inescapable impact of politics on personal lives.\"}}" |
...
This command updates the specified EditorialObject's
productionSynopsis
based on its IRI
.
4. Delete (DELETE)
To delete an EditorialObject
instance, use the following curl
command to send a DELETE
request:
Code Block | ||
---|---|---|
| ||
curl -X DELETE --data-urlencode "filter.%3Chttp%3A%2F%2Fwww.ebu.ch%2Fmetadata%2Fontologies%2Febucoreplus%23hasRelatedEditorialObject%3E=http://www.ebu.ch/metadata/ontologies/ebucoreplus/data#Asset_37f6d90c-87c9-4c1f-9a46-ff1102f9bd8a" |
...
Important Notes
Encoding URIs: When passing property
IRI
, ensure it is URL-encoded.
3. Detailed Example with Multiple Filters
Suppose you want to filter EditorialObject
instances where:
The property
title
isRun Lola Run
.The
child-to-parent
(Asset
toEditorialObject
) property<http://www.ebu.ch/metadata/ontologies/ebucoreplus#hasRelatedEditorialObject>
ishttp://www.ebu.ch/metadata/ontologies/ebucoreplus/data#Asset_37f6d90c-87c9-4c1f-9a46-ff1102f9bd8a.
Code Block | ||
---|---|---|
| ||
curl --get "http://localhost/enapso-dev/view-management/v1/editorialObject" -H "Content-Type: application/json" -d "{\"variables\": {\"iri\": \"http://ont.enapso.com/sparql-template#EditorialObject_2f9b1462-e937-4416-8c23-ce96fc42dc55\"}}" |
...
This command deletes the EditorialObject
identified by the given IRI
.
...
--data-urlencode "filter.title=Run Lola Run" --data-urlencode "filter.%3Chttp%3A%2F%2Fwww.ebu.ch%2Fmetadata%2Fontologies%2Febucoreplus%23hasRelatedEditorialObject%3E=http://www.ebu.ch/metadata/ontologies/ebucoreplus/data#Asset_37f6d90c-87c9-4c1f-9a46-ff1102f9bd8a" |
3. Update (PATCH)
To update an existing EditorialObject
, use the following curl
command to send a PATCH
request with the IRI
and new values. Make sure to include the namedGraph
key and value in the post body with the information you want to update. The namedGraph
specifies the graph in the triplestore where your information is preserved. Passing the namedGraph
is necessary when using ENAPSO together free version. Otherwise, the update operation will not perform.
Code Block | ||
---|---|---|
| ||
curl -X PATCH "http://localhost/enapso-dev/view-management/v1/editorialObject" -H "Content-Type: application/json" -d "{\"namedGraph\": \"http://www.ebu.ch/metadata/ontologies/ebucoreplus/demodata\",\"variables\": {\"iri\": \"http://ont.enapso.com/sparql-template#EditorialObject_2f9b1462-e937-4416-8c23-ce96fc42dc55\", \"productionSynopsis\": \"Directed by Florian Henckel von Donnersmarck, this sweeping historical drama delves into themes of art, love, tragedy, and the inescapable impact of politics on personal lives.\"}}" |
...
This command updates the specified EditorialObject's
productionSynopsis
based on its IRI
.
4. Delete (DELETE)
To delete an EditorialObject
class instance, use the following curl command to send a DELETE
request. Ensure that the namedGraph
key and value (namedGraph
specifies the graph in the triplestore where your information is preserved), is included in the post body with the variables
object in which you pass the IRI
of the instance you want to delete. Passing the namedGraph
is necessary when using ENAPSO together free version. Otherwise, the delete operation will not perform.
Code Block | ||
---|---|---|
| ||
curl -X DELETE "http://localhost/enapso-dev/view-management/v1/editorialObject" -H "Content-Type: application/json" -d "{\"namedGraph\": \"http://www.ebu.ch/metadata/ontologies/ebucoreplus/demodata\",\"variables\": {\"iri\": \"http://ont.enapso.com/sparql-template#EditorialObject_2f9b1462-e937-4416-8c23-ce96fc42dc55\"}}" |
...
This command deletes the EditorialObject
identified by the given IRI
.
These curl
commands provide a direct way to interact with your RESTful API, enabling you to perform create
, read
, update
, and delete
operations on EditorialObject
CORS
Setting Up CORS for Your Web Client
When setting up a web client, it is essential to configure Cross-Origin Resource Sharing (CORS) to ensure your web application can communicate with the server across different origins. Here’s how to add and configure the CORS plugin for various browsers:
Adding the CORS Plugin for Firefox, Chrome, Edge, and Safari
Firefox
Go to the Firefox Add-ons website.
Search for "CORS" and find a suitable CORS plugin.
Click "Add to Firefox" and follow the installation prompts.
Chrome
Go to the Chrome Web Store.
Search for "CORS" and find a suitable CORS plugin.
Click "Add to Chrome" and follow the installation prompts.
Edge
Go to the Microsoft Edge Add-ons website.
Search for "CORS" and find a suitable CORS plugin.
Click "Add to Edge" and follow the installation prompts.
Safari
Go to the Safari Extensions Gallery.
Search for "CORS" and find a suitable CORS plugin.
Click "Install" and follow the installation prompts.
Configuring the CORS Plugin
After installing the CORS plugin, you need to configure it to support all HTTP methods, as the default configuration might not include methods like PATCH. Follow these steps:
Open the CORS Plugin Settings
Click on the CORS plugin icon in your browser toolbar.
Go to the settings or options page of the plugin.
Allow All HTTP Methods
Ensure all HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.) are allowed.
Specifically, check and enable the PATCH method, as it might not be included by default.
Save the Configuration
Save your changes in the plugin settings.
Refresh your web application to apply the new CORS configuration.
By configuring the CORS plugin correctly, you ensure that your web client can make all necessary HTTP requests to the server without encountering CORS-related issues. This setup is crucial for the smooth functioning of your web application, especially when dealing with CRUD operations.
Summary
This setup enables you to fully utilize the RESTful interface of the ENAPSO together free platform, integrating seamlessly with your existing workflows and enhancing data manipulation capabilities through programmatically accessible endpoints. By following these steps, users can effectively create and manage REST APIs for CRUD operations, empowering them to perform sophisticated data interactions directly through HTTP requests.