Difference between revisions of "Resource Registry Service - Query Templates Management"
Luca.frosini (Talk | contribs) (→Read via REST Example) |
Luca.frosini (Talk | contribs) m (→Create via REST API Resource Example) |
||
| Line 212: | Line 212: | ||
"$state": { | "$state": { | ||
"@class": "TemplateVariable", | "@class": "TemplateVariable", | ||
| − | |||
"name": "$state", | "name": "$state", | ||
| − | "description": "The state of the EService, e.g. down, ready." | + | "description": "The state of the EService, e.g. down, ready.", |
| + | "defaultValue": "ready", | ||
} | } | ||
} | } | ||
Revision as of 18:01, 7 February 2022
These sections provide information regarding how to interact with Resource Registry Service for query templates management. This page presents REST and JAVA API for each functionality.
Please note that the provided examples can intentionally hide some details to avoid unneeded complexity.
Query Templates Management
Query Templates Management is responsible for the management of query templates. It offers the following APIs:
- List: it allows to list query templates;
- Create: it allows to create a new query template;
- Exists: it allows to check if an query template exists;
- Read: it allows to read a query template;
- Update: it allows to update a query template;
- run: it allows to run a query template by providing the template variable values;
- Delete: it allows to delete a query template.
The Query Templates Management implements the following policies:
- it manages the Header automatically;
- it allows identifying an instance via the provided name;
- it validates the query templates by applying the provided default values by running the generated query.
Please note that a query template is composed by JSON Query that uses variables.
The variables are in the form $avriableName. You can run a query template by providing the values of the variables.
Please refers to JSON Query documentation to understand how to create a JSON Query.
Query Template Collection
The following table shows the exposed APIs as REST Collection.
| Operation | HTTP Method | URL |
|---|---|---|
| List | GET | /query-templates
|
| Create | PUT | /query-templates/{QUERY_TEMPLATE_NAME}
|
| Exists | HEAD | /query-templates/{QUERY_TEMPLATE_NAME}
|
| Read | GET | /query-templates/{QUERY_TEMPLATE_NAME}
|
| Update | PUT | /query-templates/{QUERY_TEMPLATE_NAME}
|
| Run | POST | /query-templates/{QUERY_TEMPLATE_NAME}
|
| Delete | DELETE | /query-templates/{QUERY_TEMPLATE_NAME}
|
Resource Registry Query Template Client
Resource Registry Query Template Client is a java library providing RPC facilities to interact with Query Templates Management.
To use the Java library to interact with Query Template collection declare the following dependency in your pom.xml file.
<dependency> <groupId>org.gcube.information-system</groupId> <artifactId>resource-registry-query-template-client</artifactId> <version>[1.0.0,2.0.0-SNAPSHOT)</version> <dependency>
To use the client you just need to instantiate the client via the provided factory.
import org.gcube.informationsystem.resourceregistry.queries.templates.ResourceRegistryQueryTemplateClient; import org.gcube.informationsystem.resourceregistry.queries.templates.ResourceRegistryQueryTemplateClientFactory; ... ResourceRegistryQueryTemplateClient resourceRegistryQueryTemplateClient = ResourceRegistryQueryTemplateClientFactory.create();
The provided client exposes the available methods and options as explained below.
The source code of the resource-registry-query-template-client is available at https://code-repo.d4science.org/gCubeSystem/resource-registry-query-template-client
APIs
List Query Templates
List via Java Client
Signature
public List<String> all() throws ResourceRegistryException;
List via Java Client Example
The following snippet of code shows how to list all the query templates.
ResourceRegistryQueryTemplateClient resourceRegistryQueryTemplateClient = ResourceRegistryQueryTemplateClientFactory.create(); List<String> queryTemplates = resourceRegistryQueryTemplateClient.all();
List via REST API
List via REST API Example
The following request shows how to retrieve all the resource instances.
Request URL
GET /query-templates
Response Body
[ "GetAllEServiceWithState", "GetAllSpecificEServiceWithState", ... ]
Create Query Template
Create via Java Client
Signature
...
Create via Java Client Example
...
Create via REST API
PUT /query-templates/{QUERY_TEMPLATE_NAME}
Create via REST API Resource Example
The following listing shows an example of EService representation to be created.
Request URL
PUT /query-templates/GetAllEServiceWithState
Request Body
{ "@class": "QueryTemplate", "name" : "GetAllEServiceWithState", "description": "The following query return all the EService having the state provided as parameters, e.g. down, ready. The content of the request to run this query template will be something like {\"$state\": \"ready\"}", "template": { "@class": "EService", "consistsOf": [{ "@class": "ConsistsOf", "target": { "@class": "StateFacet", "value": "$state" } }] }, "templateVariables" : { "$state" : { "@class": "TemplateVariable", "name": "$state", "description": "The state of the EService, e.g. down, ready.", "defaultValue": "ready" } } }
Response Body
{ "@class": "QueryTemplate", "header": { "@class": "Header", "uuid": "fcc01dd3-5ee1-4228-87fd-92e205a86c40", "createdBy": "luca.frosini", "creationTime": "2022-02-07 17:53:46.528 +0100", "lastUpdateBy": "luca.frosini", "lastUpdateTime": "2022-02-07 17:53:46.528 +0100" }, "name": "GetAllEServiceWithState", "description": "The following query return all the EService having the state provided as parameters, e.g. down, ready. The content of the request to run this query template will be something like {\"$state\": \"ready\"}", "template": { "@class": "EService", "consistsOf": [{ "@class": "ConsistsOf", "target": { "@class": "StateFacet", "value": "$state" } }] }, "templateVariables": { "$state": { "@class": "TemplateVariable", "name": "$state", "description": "The state of the EService, e.g. down, ready.", "defaultValue": "ready", } } }
Read Query Template
Read via Java Client
...
Read via Java Client Example
...
Read via REST API
GET /query-templates/{QUERY_TEMPLATE_NAME}
Read via REST Example
Request URL
GET /query-templates/GetAllEServiceWithState
Response Body
{ "@class": "QueryTemplate", "header": { "@class": "Header", "uuid": "fcc01dd3-5ee1-4228-87fd-92e205a86c40", "createdBy": "luca.frosini", "creationTime": "2022-02-07 17:53:46.528 +0100", "lastUpdateBy": "luca.frosini", "lastUpdateTime": "2022-02-07 17:53:46.528 +0100" }, "name": "GetAllEServiceWithState", "description": "The following query return all the EService having the state provided as parameters, e.g. down, ready. The content of the request to run this query template will be something like {\"$state\": \"ready\"}", "template": { "@class": "EService", "consistsOf": [{ "@class": "ConsistsOf", "target": { "@class": "StateFacet", "value": "$state" } }] }, "templateVariables": { "$state": { "@class": "TemplateVariable", "defaultValue": "ready", "name": "$state", "description": "The state of the EService, e.g. down, ready." } } }
Update Instance
Update via Java Client
Signature
...
Update via Java Client Example
...
Update via REST API
PUT /query-templates/{QUERY_TEMPLATE_NAME}
Update via REST API Resource Example
The following listing shows an example of a template update.
Request URL
PUT /query-templates/GetAllEServiceWithState
Request Body
{ "@class": "QueryTemplate", "header": { "@class": "Header", "uuid": "459c1658-b9d9-4ec7-9ff2-a019af45f0e9" } "name" : "GetAllEServiceWithState", "description": "The following query return all the EService having the state provided as parameters, e.g. down, ready. The content of the request to run this query template will be something like {\"$state\": \"down\"}", "template": { "@class": "EService", "consistsOf": [{ "@class": "ConsistsOf", "target": { "@class": "StateFacet", "value": "$state" } }] }, "templateVariables" = { "$state" : { "@class": "TemplateVariable", "name": "$state", "description": "The state of the EService, e.g. down, ready.", "defaultValue": "down" } } }
Response Body
{ "@class": "QueryTemplate", "header": { "@class": "Header", "uuid": "459c1658-b9d9-4ec7-9ff2-a019af45f0e9", "createdBy": "luca.frosini", "creationTime": "2022-01-28 19:33:12.395 +0100", "lastUpdateBy": "luca.frosini" "lastUpdateTime": "2022-01-28 19:35:32.125 +0100" } "name" : "GetAllEServiceWithState", "description": "The following query return all the EService having the state provided as parameters, e.g. down, ready. The content of the request to run this query template will be something like {\"$state\": \"down\"}", "template": { "@class": "EService", "consistsOf": [{ "@class": "ConsistsOf", "target": { "@class": "StateFacet", "value": "$state" } }] }, "templateVariables" = { "$state" : { "@class": "TemplateVariable", "name": "$state", "description": "The state of the EService, e.g. down, ready.", "defaultValue": "down" } } }
Run Query Template
Run via Java Client
...
Run via Java Client Example
...
Run via REST API
POST /query-templates/{QUERY_TEMPLATE_NAME}
Run via REST Example
Request URL
POST /query-templates/GetAllEServiceWithState
Request Body
{ "$state" : "down" }
The response will contain a JSON array containing all the EService instances which are down.
Delete Query Template
Delete via Java Client
...
Delete via Java Client Example
...
Delete via REST API
DELETE /query-templates/{QUERY_TEMPLATE_NAME}
Delete via REST Example
Request URL
DELETE /query-templates/GetAllEServiceWithState
