Package org.gcube.informationsystem.resourceregistry.rest

Class Access

java.lang.Object
org.gcube.informationsystem.resourceregistry.rest.BaseRest
org.gcube.informationsystem.resourceregistry.rest.Access
@Path("access") public class Access extends BaseRest
Author:
Luca Frosini (ISTI - CNR)

  • Field Details

    • RESOURCE_TYPE_PATH_PARAMETER

      public static final String RESOURCE_TYPE_PATH_PARAMETER
      Constant representing the resource type name path parameter.
      See Also:

    • RELATION_TYPE_PATH_PARAMETER

      public static final String RELATION_TYPE_PATH_PARAMETER
      Constant representing the relation type name path parameter.
      See Also:

    • REFERENCE_TYPE_PATH_PARAMETER

      public static final String REFERENCE_TYPE_PATH_PARAMETER
      Constant representing the reference type name path parameter.
      See Also:

    • RAW_QUERY_METHOD

      public static final String RAW_QUERY_METHOD
      Constant representing the method name for executing raw queries.
      See Also:

    • GRAPH_QUERY_METHOD

      public static final String GRAPH_QUERY_METHOD
      Constant representing the method name for executing graph queries.
      See Also:

    • JSON_QUERY_METHOD

      public static final String JSON_QUERY_METHOD
      Constant representing the method name for executing json queries.
      See Also:

    • PREPARED_QUERY_METHOD

      public static final String PREPARED_QUERY_METHOD
      Constant representing the method name for executing prepared queries.
      See Also:

  • Constructor Details

    • Access

      public Access()
      Default constructor for the Access class. Initializes a new instance of the Access class.

  • Method Details

    • listContexts

      @GET @Path("contexts") @Produces("application/json;charset=UTF-8") public String listContexts() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves the list of contexts in the system. The response can include metadata and provides pagination based on query parameters and user authorization. REST Endpoint: GET /access/contexts[?limit={limit}&offset={offset}&includeMeta={true|false}] Request Examples:
      • GET /access/contexts (returns first 10 contexts - default pagination)
      • GET /access/contexts?limit=20 (returns first 20 contexts)
      • GET /access/contexts?offset=10 (returns 10 contexts starting from the 11th - default limit with offset)
      • GET /access/contexts?limit=5&offset=15 (returns 5 contexts starting from the 16th)
      • GET /access/contexts?includeMeta=true (returns first 10 contexts with metadata - for non-admin users)
      • GET /access/contexts?limit=20&includeMeta=true (returns first 20 contexts with metadata).
      Query Parameters: limit (optional):
      • Maximum number of contexts to return in a single response
      • Default value: 10
      • Example: ?limit=50 (returns at most 50 contexts).
      offset (optional):
      • Number of contexts to skip from the beginning of the result set
      • Default value: 0 (starts from the first context)
      • Example: ?offset=100 (skips the first 100 contexts)
      • Commonly used with limit for pagination: ?limit=50&offset=100.
      includeMeta (optional): Whether to include metadata in the response (for non-admin users).
      • Default value: false (basic information only)
      • Values: true|false
      • Example: ?includeMeta=true (includes metadata with obfuscated sensitive fields)
      • Note: IS-Manager and Infrastructure-Manager always receive not filtered metadata regardless of this parameter.
      Authorization Requirements: IS-Manager:
      • Automatically receive full context information including:
      • Complete metadata (createdBy, lastUpdateBy, creation/modification dates)
      • Context state information
      • All context properties without obfuscation.
      • Metadata is included by default regardless of request parameters.
      Infrastructure-Manager:
      • Automatically receive full context information including:
      • Complete metadata (createdBy, lastUpdateBy, creation/modification dates)
      • Context state information
      • All context properties without obfuscation.
      • Metadata is included by default regardless of request parameters.
      Other Users:
      • Receive basic context information by default
      • Can explicitly request metadata via includeMeta=true query parameter
      • When metadata is requested, receive metadata with sensitive information filtered:
      • Date fields (creation, modification) are visible
      • User identifiers (createdBy, lastUpdateBy) are obfuscated or hidden
      • Other administrative details may be filtered.
      Response Codes:
      • 200 OK: Contexts successfully retrieved
      • 403 Forbidden: User lacks authorization to access context information
      • 500 Internal Server Error: Server error during context retrieval.
      Response Format:
      • Content-Type: application/json
      • Body: JSON array containing context objects with role-appropriate detail level
      • Pagination information may be included in response headers.
      Returns:
      JSON array containing context objects with role-appropriate detail level
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if contexts cannot be retrieved

    • readContext

      @GET @Path("contexts/{context-uuid}") @Produces("application/json;charset=UTF-8") public String readContext(@PathParam("context-uuid") String uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves a specific context by its UUID. The response includes metadata and detail level based on query parameters and user authorization. REST Endpoint: GET /access/contexts/{context-uuid}[?includeMeta={true|false}] Request Examples:
      • GET /access/contexts/c0f314e7-2807-4241-a792-2a6c79ed4fd0 (returns basic context information)
      • GET /access/contexts/c0f314e7-2807-4241-a792-2a6c79ed4fd0?includeMeta=true (returns context with metadata - for non-admin users)
      • GET /access/contexts/CURRENT_CONTEXT (returns the current context - retrieved from client's authorization token).
      Path Parameters: context-uuid (required):
      • The unique identifier of the context to retrieve
      • Must be a valid UUID string format (e.g., "c0f314e7-2807-4241-a792-2a6c79ed4fd0")
      • Special keyword: "CURRENT_CONTEXT" to retrieve the context from client's authorization token
      • When using "CURRENT_CONTEXT", the actual context is extracted from the JWT token sent by the client
      • Example: GET /access/contexts/CURRENT_CONTEXT returns the context the client is authorized for.
      Query Parameters: includeMeta (optional): Whether to include metadata in the response (for non-admin users).
      • Default value: false (basic information only)
      • Values: true|false
      • Example: ?includeMeta=true (includes metadata with obfuscated sensitive fields)
      • Note: IS-Manager and Infrastructure-Manager always receive metadata regardless of this parameter.
      Authorization Requirements: IS-Manager:
      • Can retrieve context information for any context without restrictions
      • Automatically receive full context information including complete metadata
      • All context properties and state information without obfuscation
      • Metadata is included by default regardless of request parameters.
      Infrastructure-Manager:
      • Can retrieve context information for any context without restrictions
      • Automatically receive full context information including complete metadata
      • All context properties and state information without obfuscation
      • Metadata is included by default regardless of request parameters.
      Context-Manager:
      • When operating in their own context (using a token from that context):
      • Receive full context information like IS-Manager and Infrastructure-Manager
      • Complete metadata without obfuscation
      • All context properties and state information.
      • When operating outside their context or requesting other contexts:
      • Receive basic context information by default
      • Can request metadata via includeMeta=true with obfuscated sensitive fields.
      Other Users:
      • Receive basic context information by default
      • Can explicitly request metadata via includeMeta=true query parameter
      • When metadata is requested, receive metadata with sensitive information filtered:
      • Date fields (creation, modification) are visible
      • User identifiers (createdBy, lastUpdateBy) are obfuscated or hidden
      • Other administrative details may be filtered.
      Response Codes:
      • 200 OK: Context successfully retrieved
      • 404 Not Found: Context with the specified UUID does not exist
      • 403 Forbidden: User lacks authorization to access the specific context
      • 400 Bad Request: Invalid UUID format.
      Response Format:
      • Content-Type: application/json
      • Body: JSON object containing the context with role-appropriate detail level
      • Includes context properties, metadata (if authorized), and state information.
      Parameters:
      uuid - the UUID of the context to retrieve, or "CURRENT_CONTEXT" to get the context from client's authorization token
      Returns:
      JSON object containing the context with role-appropriate detail level
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context with the specified UUID is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if there is an error accessing the resource registry

    • readType

      @GET @Path("types/{type-name}") @Produces("application/json;charset=UTF-8") public String readType(@PathParam("type-name") String type, @QueryParam("polymorphic") @DefaultValue("false") Boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves the schema definition(s) for the specified type. The response can include subtypes and metadata based on query parameters and user authorization. REST Endpoint: GET /access/types/{type-name}[?polymorphic={true|false}&includeMeta={true|false}] Request Examples:
      • GET /access/types/ContactFacet (returns basic ContactFacet type definition only)
      • GET /access/types/ContactFacet?polymorphic=true (returns ContactFacet and all its subtypes)
      • GET /access/types/ContactFacet?includeMeta=true (returns ContactFacet with metadata for authorized users)
      • GET /access/types/ContactFacet?polymorphic=true&includeMeta=true (returns ContactFacet, subtypes, and metadata).
      Path Parameters:
      • type-name: The name of the type to retrieve (case-sensitive).
      Query Parameters: polymorphic (optional): Whether to include subtypes in the response.
      • Default value: false (returns only the specified type)
      • When true: returns the specified type AND all its existing subtypes
      • When false: returns only the specified type definition
      • Note: No pagination is applied - ALL subtypes are returned when polymorphic=true
      • Example: ?polymorphic=true (includes all subtypes of the requested type).
      includeMeta (optional): Whether to include metadata in the response.
      • Default value: false (basic type information only)
      • Values: true|false
      • Example: ?includeMeta=true (includes metadata based on user authorization).
      Authorization Requirements: IS-Manager:
      • Receive basic type information by default
      • Can explicitly request metadata via includeMeta=true query parameter
      • When metadata is requested, receive complete type definitions with full metadata
      • All metadata fields are included when includeMeta=true
      • No obfuscation or filtering of sensitive information.
      Infrastructure-Manager:
      • Receive basic type information by default
      • Can explicitly request metadata via includeMeta=true query parameter
      • When metadata is requested, receive complete type definitions with full metadata
      • All metadata fields are included when includeMeta=true
      • No obfuscation or filtering of sensitive information.
      Other Users:
      • Receive basic type information by default
      • Can explicitly request metadata via includeMeta=true query parameter
      • When metadata is requested, receive metadata with sensitive information filtered:
      • Date fields (creation, modification) are visible
      • User identifiers (createdBy, lastUpdateBy) are obfuscated or hidden
      • Other administrative details may be filtered.
      Response Codes:
      • 200 OK: Type successfully retrieved
      • 404 Not Found: Type with the specified name does not exist
      • 403 Forbidden: User lacks authorization to access type information.
      Response Format:
      • Content-Type: application/json
      • Body: Type schema definition(s) with authorization-appropriate detail level
      • When polymorphic=false: single type definition object
      • When polymorphic=true: array of type definitions (parent + all subtypes).
      Parameters:
      type - the name of the type to retrieve (case-sensitive)
      polymorphic - whether to include subtypes in the response (default: false)
      Returns:
      JSON containing type schema definition(s) with authorization-appropriate detail level
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the specified type is not found in the system
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if there is an error retrieving the type definitions

    • listQueryTemplates

      @GET @Path("query-templates") @Consumes({"text/plain","application/json;charset=UTF-8"}) @Produces("application/json;charset=UTF-8") public String listQueryTemplates() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves all query templates from the Resource Registry. REST Endpoint: GET /access/query-templates Request Examples:
      • Basic query: GET /access/query-templates
      • With pagination: GET /access/query-templates?limit=20&offset=40
      • With metadata: GET /access/query-templates?includeMeta=true
      • Combined parameters: GET /access/query-templates?limit=15&offset=30&includeMeta=true.
      Query Parameters: limit (optional):
      • Maximum number of query templates to return in a single response
      • Default value: 10
      • Example: ?limit=50 (returns at most 50 query templates).
      offset (optional):
      • Number of query templates to skip from the beginning of the result set
      • Default value: 0 (starts from the first query template)
      • Example: ?offset=100 (skips the first 100 query templates).
      includeMeta (optional): Whether to include metadata in the response query templates.
      • Default value: false (basic information only)
      • Values: true|false
      • Example: ?includeMeta=true (includes metadata with appropriate filtering based on user role)
      • Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      Authorization Requirements: IS-Manager:
      • Full access to query templates
      • Receives complete, unfiltered metadata including all administrative fields.
      Infrastructure-Manager:
      • Full access to query templates
      • Receives complete, unfiltered metadata including all administrative fields.
      Other Users:
      • Basic access with metadata filtering
      • Receive metadata with sensitive information filtered when includeMeta=true.
      Response Codes:
      • 200 OK: Query templates successfully retrieved
      • 400 Bad Request: Invalid query parameters (e.g., invalid limit/offset values)
      • 403 Forbidden: Insufficient permissions to access query templates.
      Response Format:
      • Returns a JSON array containing the requested query templates
      • Each query template includes its name, description, template definition, template variables, and metadata (if requested)
      • Empty array is returned if no query templates exist in the accessible contexts.
      Example Metadata (filtered for non-admin users): ``json "metadata": { "type": "Metadata", "creationTime": "2025-03-18 17:13:40.952 +0100", "createdBy": "HIDDEN_FOR_PRIVACY", "lastUpdateBy": "HIDDEN_FOR_PRIVACY", "lastUpdateTime": "2025-03-19 16:21:16.805 +0100" } ``
      Returns:
      JSON array containing the requested query templates with their properties and metadata (if requested)
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If query templates cannot be retrieved
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query template retrieval

    • readQueryTemplate

      @GET @Path("query-templates/{query-template-name}") @Produces("application/json;charset=UTF-8") public String readQueryTemplate(@PathParam("query-template-name") String queryTemplateName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves a specific query template by its name from the Resource Registry. REST Endpoint: GET /access/query-templates/{query-template-name} Request Examples:
      • Basic retrieval: GET /access/query-templates/GetAllEServiceWithState
      • With metadata: GET /access/query-templates/GetAllEServiceWithState?includeMeta=true.
      Path Parameters:
      • query-template-name: The name of the query template to retrieve (e.g., "GetAllEServiceWithState").
      Query Parameters: includeMeta (optional): Whether to include metadata in the response query template.
      • Default value: false (basic information only)
      • Values: true|false
      • Example: ?includeMeta=true (includes metadata with appropriate filtering based on user role)
      • Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      Authorization Requirements: IS-Manager:
      • Full access to query template
      • Receives complete, unfiltered metadata including all administrative fields.
      Infrastructure-Manager:
      • Full access to query template
      • Receives complete, unfiltered metadata including all administrative fields.
      Other Users:
      • Basic access with metadata filtering
      • Receive metadata with sensitive information filtered when includeMeta=true.
      Response Codes:
      • 200 OK: Query template successfully retrieved
      • 404 Not Found: Query template with the specified name does not exist
      • 403 Forbidden: Insufficient permissions to access the query template.
      Response Format:
      • Returns a JSON object containing the requested query template
      • Includes name, description, template definition, template variables, and metadata (if requested).
      Example Metadata (filtered for non-admin users): ``json "metadata": { "type": "Metadata", "creationTime": "2025-03-18 17:13:40.952 +0100", "createdBy": "HIDDEN_FOR_PRIVACY", "lastUpdateBy": "HIDDEN_FOR_PRIVACY", "lastUpdateTime": "2025-03-19 16:21:16.805 +0100" } ``
      Parameters:
      queryTemplateName - The name of the query template to retrieve
      Returns:
      JSON object containing the requested query template with its properties and metadata (if requested)
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the query template with the specified name does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query template retrieval

    • runQueryTemplate

      @POST @Path("query-templates/{query-template-name}") @Produces("application/json;charset=UTF-8") public String runQueryTemplate(@PathParam("query-template-name") String queryTemplateName, String params) throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Executes a query template with the specified name and parameters in the Resource Registry. REST Endpoint: POST /access/query-templates/{query-template-name} Request Examples:
      • Basic execution: POST /access/query-templates/GetAllEServiceWithState
      • With polymorphic disabled: POST /access/query-templates/GetAllEServiceWithState?polymorphic=false
      • With metadata: POST /access/query-templates/GetAllEServiceWithState?includeMeta=true
      • Hierarchical (admin only): POST /access/query-templates/GetAllEServiceWithState?hierarchical=true
      • Full metadata context: POST /access/query-templates/GetAllEServiceWithState?includeMeta=true&allMeta=true
      • With context information: POST /access/query-templates/GetAllEServiceWithState?includeContexts=true.
      Path Parameters:
      • query-template-name: The name of the query template to execute (e.g., "GetAllEServiceWithState").
      Request Body:
      • JSON object containing parameter values to substitute in the query template
      • Parameters not provided in the body will use their default values from the template definition
      • Parameter names must match those defined in the template's templateVariables section.
      Example Request Body for GetAllEServiceWithState: ``json { "$state" : "down" } ` <strong>Query Parameters:</strong> <strong>polymorphic</strong> (optional): Whether the query should consider instances polymorphically (include subtypes). <ul> <li>Default value: true (includes all subtypes)</li> <li>Values: true|false</li> <li>Example: ?polymorphic=false (exact type match only, may slow down the query)</li> <li>When false, only instances of the exact types defined in the query are returned</li> <li>When true, instances of derived types are also included.</li> </ul> <strong>includeMeta</strong> (optional): Whether to include metadata in the response instances. <ul> <li>Default value: false (basic information only)</li> <li>Values: true|false</li> <li>Example: ?includeMeta=true (includes metadata with appropriate filtering based on user role)</li> <li><strong>Effect</strong>: Only applies when query returns complete instances of defined types</li> <li><strong>No Effect</strong>: When query uses _emit to return individual fields instead of complete instances</li> <li><strong>Restriction:</strong> IS-Manager and Infrastructure-Manager see complete metadata; other users see filtered metadata with sensitive fields obfuscated.</li> </ul> <strong>allMeta</strong> (optional): Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.). <ul> <li>Must be used in conjunction with includeMeta=true</li> <li>Default value: false (metadata only for main instances, more human-readable)</li> <li>Values: true|false</li> <li>Example: ?includeMeta=true&amp;allMeta=true (includes metadata for all nested elements)</li> <li><strong>Effect</strong>: Only applies when query returns complete instances of defined types</li> <li><strong>No Effect</strong>: When query uses _emit to return individual fields instead of complete instances.</li> </ul> <strong>hierarchical</strong> (optional, admin-only): Whether to execute the query across child contexts of the current context. <ul> <li>Default value: false (current context only)</li> <li>Values: true|false</li> <li><strong>Restriction:</strong> Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles (Context-Manager must be of the current context derived from the authorization token)</li> <li>Example: ?hierarchical=true (executes query in current and child contexts)</li> <li>Current context is determined from the authorization token.</li> </ul> <strong>includeContexts</strong> (optional): Whether to include the list of contexts where each returned instance is available. <ul> <li>Default value: false (context information not included)</li> <li>Values: true|false</li> <li>Example: ?includeContexts=true (shows context availability for each instance)</li> <li><strong>Effect</strong>: Only applies when query returns complete instances of defined types</li> <li><strong>No Effect</strong>: When query uses _emit to return individual fields instead of complete instances</li> <li><strong>Note:</strong> A Resource is present in all contexts that form the union of contexts of all its Facets.</li> </ul> <strong>Authorization Requirements:</strong> <strong>IS-Manager:</strong> <ul> <li>Full access to execute query template</li> <li>Can use hierarchical querying across all contexts</li> <li>Receives complete, unfiltered metadata including all administrative fields.</li> </ul> <strong>Infrastructure-Manager:</strong> <ul> <li>Full access to execute query template</li> <li>Can use hierarchical querying across all contexts</li> <li>Receives complete, unfiltered metadata including all administrative fields.</li> </ul> <strong>Context-Manager:</strong> <ul> <li>Can execute query templates with hierarchical querying within their managed context hierarchy</li> <li>Must be Context-Manager of the current context (derived from the authorization token)</li> <li>Receives complete, unfiltered metadata including all administrative fields.</li> </ul> <strong>Other Users:</strong> <ul> <li>Can execute query templates in the current context only</li> <li>Cannot use hierarchical querying (hierarchical parameter ignored)</li> <li>Receive metadata with sensitive information filtered when includeMeta=true.</li> </ul> <strong>Operation Behavior:</strong> <ul> <li><strong>Parameter Substitution</strong>: Parameters in the template query (prefixed with $) are replaced with values from the request body</li> <li><strong>Default Values</strong>: Parameters not provided in the request body use their default values from the template definition</li> <li><strong>Query Execution</strong>: The resulting query is executed against the Resource Registry</li> <li><strong>Response Type</strong>: Can return complete instances or individual fields (when using _emit in the query)</li> <li><strong>Metadata Effect</strong>: includeMeta, allMeta, and includeContexts only affect queries returning complete instances, not _emit queries</li> <li><strong>Polymorphic Behavior</strong>: When disabled (polymorphic=false), may impact query performance but ensures exact type matching</li> <li><strong>No Pagination</strong>: Pagination is not currently supported for query template execution.</li> </ul> <strong>Response Codes:</strong> <ul> <li><strong>200 OK</strong>: Query template successfully executed</li> <li><strong>400 Bad Request</strong>: Invalid query parameters or malformed parameter values</li> <li><strong>404 Not Found</strong>: Query template with the specified name does not exist</li> <li><strong>403 Forbidden</strong>: Insufficient permissions to execute the query template.</li> </ul> <strong>Response Format:</strong> <ul> <li>Returns query results based on the template definition</li> <li>For complete instances: JSON array containing instances with properties, relations, and metadata (if requested)</li> <li>For _emit queries: JSON array containing individual field values as specified in the query</li> <li>Response structure depends on the query template and parameter values provided.</li> </ul> <strong>Example Metadata (filtered for non-admin users, only for complete instances):</strong> `json "metadata": { "type": "Metadata", "creationTime": "2025-03-18 17:13:40.952 +0100", "createdBy": "HIDDEN_FOR_PRIVACY", "lastUpdateBy": "HIDDEN_FOR_PRIVACY", "lastUpdateTime": "2025-03-19 16:21:16.805 +0100" } ``
      Parameters:
      queryTemplateName - The name of the query template to execute
      params - JSON object containing parameter values for template substitution
      Returns:
      JSON array containing query results based on the template definition and parameters
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the query template with the specified name does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - If the query execution fails due to invalid parameters or query structure
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query template execution

    • listInstances

      @GET @Path("instances/{type-name}") @Produces("application/json;charset=UTF-8") public String listInstances(@PathParam("type-name") String type, @QueryParam("polymorphic") @DefaultValue("true") Boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves all instances of a specified type from the Resource Registry. REST Endpoint: GET /access/instances/{type-name} Request Examples:
      • Basic query: GET /access/instances/EService
      • With pagination: GET /access/instances/EService?limit=20&offset=40
      • With subtypes and metadata: GET /access/instances/EService?polymorphic=true&includeMeta=true
      • Full metadata context: GET /access/instances/EService?includeMeta=true&allMeta=true
      • With context information: GET /access/instances/EService?includeContexts=true
      • Hierarchical (admin only): GET /access/instances/EService?hierarchical=true
      • Hierarchical with contexts (admin only): GET /access/instances/EService?hierarchical=true&includeContexts=true.
      Path Parameters:
      • type-name: The name of the Information System type whose instances should be retrieved (e.g., "EService", "ContactFacet").
      Query Parameters: polymorphic (optional): Whether to include instances of subtypes in the response.
      • Default value: true (includes all subtypes)
      • Values: true|false
      • Example: ?polymorphic=false (returns only exact type instances).
      limit (optional):
      • Maximum number of instances to return in a single response
      • Default value: 10
      • Example: ?limit=50 (returns at most 50 instances).
      offset (optional):
      • Number of instances to skip from the beginning of the result set
      • Default value: 0 (starts from the first instance)
      • Example: ?offset=100 (skips the first 100 instances).
      includeMeta (optional): Whether to include metadata in the response instances.
      • Default value: false (basic information only)
      • Values: true|false
      • Example: ?includeMeta=true (includes metadata with appropriate filtering based on user role)
      • Metadata includes only the requested type and subtypes (if polymorphic=true)
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (optional): Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.).
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main instances, more human-readable)
      • Values: true|false
      • Example: ?includeMeta=true&allMeta=true (includes metadata for all nested elements)
      • Purpose: When false, produces more human-readable responses with less JSON to process.
      hierarchical (optional, admin-only): Whether to include instances from child contexts of the current context.
      • Default value: false (current context only)
      • Values: true|false
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles (Context-Manager must be of the current context derived from the authorization token)
      • Example: ?hierarchical=true (includes instances from current and child contexts)
      • Current context is determined from the authorization token.
      includeContexts (optional): Whether to include the list of contexts where each instance is available.
      • Default value: false (context information not included)
      • Values: true|false
      • Example: ?includeContexts=true (shows context availability for each instance)
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present.
      Authorization Requirements: IS-Manager:
      • Full access to all metadata and hierarchical querying capabilities
      • Can access instances across all contexts
      • Receives complete, unfiltered metadata including all administrative fields.
      Infrastructure-Manager:
      • Full access to all metadata and hierarchical querying capabilities
      • Can access instances across all contexts
      • Receives complete, unfiltered metadata including all administrative fields.
      Context-Manager:
      • Full access to all metadata and hierarchical querying capabilities
      • Must be Context-Manager of the current context derived from the authorization token
      • Can access hierarchical querying capabilities
      • Receives complete, unfiltered metadata including all administrative fields.
      Other Users:
      • Basic access with metadata filtering and no hierarchical querying
      • Cannot use hierarchical querying (hierarchical parameter ignored)
      • Receive metadata with sensitive information filtered when includeMeta=true.
      Response Codes:
      • 200 OK: Instances successfully retrieved
      • 400 Bad Request: Invalid query parameters (e.g., invalid limit/offset values)
      • 404 Not Found: The specified type does not exist
      • 403 Forbidden: Insufficient permissions to access instances in the current context.
      Response Format:
      • Returns a JSON array containing the requested instances
      • Each instance includes its properties, relations, and metadata (if requested)
      • Empty array is returned if no instances of the specified type exist in the accessible contexts.
      Example Metadata (filtered for non-admin users): ``json "metadata": { "type": "Metadata", "creationTime": "2025-03-18 17:13:40.952 +0100", "createdBy": "HIDDEN_FOR_PRIVACY", "lastUpdateBy": "HIDDEN_FOR_PRIVACY", "lastUpdateTime": "2025-03-19 16:21:16.805 +0100" } ``
      Parameters:
      type - The name of the Information System type whose instances to retrieve
      polymorphic - Whether to include instances of subtypes (default: true)
      Returns:
      JSON array containing the requested instances with their properties and relations
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the specified type does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance retrieval

    • existsInstance

      @HEAD @Path("instances/{type-name}/{instance-uuid}") @Produces("application/json;charset=UTF-8") public jakarta.ws.rs.core.Response existsInstance(@PathParam("type-name") String type, @PathParam("instance-uuid") String uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Checks if an instance with the specified type and UUID exists in the Resource Registry. REST Endpoint: HEAD /access/instances/{type-name}/{instance-uuid} Request Examples:
      • Basic check: HEAD /access/instances/EService/48af15ad-7e56-4157-b624-71c98cea4f8f
      • Hierarchical check (admin only): HEAD /access/instances/EService/48af15ad-7e56-4157-b624-71c98cea4f8f?hierarchical=true.
      Path Parameters:
      • type-name: The name of the Information System type (e.g., "EService", "ContactFacet")
      • instance-uuid: The unique identifier of the instance to check.
      Query Parameters: hierarchical (optional, admin-only): Whether to check for instance existence in child contexts of the current context.
      • Default value: false (current context only)
      • Values: true|false
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles (Context-Manager must be of the current context derived from the authorization token)
      • Example: ?hierarchical=true (checks current context and all child contexts)
      • Current context is determined from the authorization token.
      Authorization Requirements: IS-Manager:
      • Can check existence of any instance type in any context
      • Can use hierarchical querying to check across context hierarchies
      • Has full administrative access to existence checking.
      Infrastructure-Manager:
      • Can check existence of any instance type in any context
      • Can use hierarchical querying to check across context hierarchies
      • Has full administrative access to existence checking.
      Context-Manager:
      • Can check existence of instances in the current context
      • Can use hierarchical querying within their managed context hierarchy
      • Must be Context-Manager of the current context (derived from the authorization token)
      • Cannot check instances in contexts where they don't have Context-Manager role.
      Other Users:
      • Can check existence of instances in the current context only
      • Cannot use hierarchical querying (parameter is ignored)
      • Only within contexts where they have authorized access through their token.
      Response Codes:
      • 204 No Content: Instance exists and is accessible in the current context
      • 404 Not Found: Instance does not exist
      • 403 Forbidden: Instance exists but is available in another context (not accessible in current context).
      Parameters:
      type - The name of the Information System type
      uuid - The unique identifier of the instance to check
      Returns:
      HTTP response with appropriate status code (204, 404, or 403)
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the specified type or instance does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the existence check

    • readInstance

      @GET @Path("instances/{type-name}/{instance-uuid}") @Produces("application/json;charset=UTF-8") public String readInstance(@PathParam("type-name") String type, @PathParam("instance-uuid") String uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves a single instance with the specified type and UUID. REST Endpoint: GET /access/instances/{type-name}/{instance-uuid} Request Examples:
      • Basic query: GET /access/instances/EService/48af15ad-7e56-4157-b624-71c98cea4f8f
      • With metadata: GET /access/instances/EService/48af15ad-7e56-4157-b624-71c98cea4f8f?includeMeta=true
      • Full metadata context: GET /access/instances/EService/48af15ad-7e56-4157-b624-71c98cea4f8f?includeMeta=true&amp;allMeta=true
      • With context information: GET /access/instances/EService/48af15ad-7e56-4157-b624-71c98cea4f8f?includeContexts=true
      • Hierarchical (admin only): GET /access/instances/EService/48af15ad-7e56-4157-b624-71c98cea4f8f?hierarchical=true
      • Hierarchical with contexts (admin only): GET /access/instances/EService/48af15ad-7e56-4157-b624-71c98cea4f8f?hierarchical=true&includeContexts=true.
      Path Parameters:
      • type-name: The name of the Information System type (e.g., "EService", "ContactFacet")
      • instance-uuid: The unique identifier of the instance to retrieve (e.g., "48af15ad-7e56-4157-b624-71c98cea4f8f").
      Query Parameters: includeMeta (optional): Whether to include metadata in the response instance.
      • Default value: false (basic information only)
      • Values: true|false
      • Example: ?includeMeta=true (includes metadata with appropriate filtering based on user role)
      • Metadata includes the requested instance and nested elements based on polymorphic setting
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (optional): Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.).
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main instance, more human-readable)
      • Values: true|false
      • Example: ?includeMeta=true&allMeta=true (includes metadata for all nested elements)
      • Purpose: When false, produces more human-readable responses with less JSON to process.
      hierarchical (optional, admin-only): Whether to retrieve the instance from child contexts of the current context.
      • Default value: false (current context only)
      • Values: true|false
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles (Context-Manager must be of the current context derived from the authorization token)
      • Example: ?hierarchical=true (searches current and child contexts for the instance)
      • Current context is determined from the authorization token.
      includeContexts (optional): Whether to include the list of contexts where the instance and its nested elements are available.
      • Default value: false (context information not included)
      • Values: true|false
      • Example: ?includeContexts=true (shows context availability for the instance and nested elements)
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present.
      Authorization Requirements: IS-Manager:
      • Full access to retrieve any instance in any context
      • Can use hierarchical querying to search across context hierarchies
      • Receive complete, unfiltered metadata for the instance and all nested elements
      • Metadata includes all administrative fields without obfuscation.
      Infrastructure-Manager:
      • Full access to retrieve any instance in any context
      • Can use hierarchical querying to search across context hierarchies
      • Receive complete, unfiltered metadata for the instance and all nested elements
      • Metadata includes all administrative fields without obfuscation.
      Context-Manager:
      • Can retrieve instances in the current context and child contexts
      • Can use hierarchical querying within their managed context hierarchy
      • Must be Context-Manager of the current context (derived from the authorization token)
      • Receive complete, unfiltered metadata for the instance and all nested elements
      • Metadata includes all administrative fields without obfuscation.
      Other Users:
      • Can retrieve instances in the current context only
      • Cannot use hierarchical querying (hierarchical parameter ignored)
      • Receive metadata with sensitive information filtered when includeMeta=true:
      • Date fields (creation, modification) are visible
      • User identifiers (createdBy, lastUpdateBy) are obfuscated or hidden
      • Other administrative details may be filtered.
      Response Codes:
      • 200 OK: Instance successfully retrieved
      • 404 Not Found: Instance does not exist
      • 403 Forbidden: Instance exists but is available in another context (not accessible in current context).
      Response Format:
      • Returns a JSON object containing the requested instance
      • Includes its properties, relations, and metadata (if requested)
      • Nested elements are included based on polymorphic and metadata settings.
      Example Metadata (filtered for non-admin users): ``json "metadata": { "type": "Metadata", "creationTime": "2025-03-18 17:13:40.952 +0100", "createdBy": "HIDDEN_FOR_PRIVACY", "lastUpdateBy": "HIDDEN_FOR_PRIVACY", "lastUpdateTime": "2025-03-19 16:21:16.805 +0100" } ``
      Parameters:
      type - The name of the Information System type
      uuid - The unique identifier of the instance to retrieve
      Returns:
      JSON object containing the requested instance with its properties and relations
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the specified type or instance does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance retrieval

    • getInstanceContexts

      @GET @Path("instances/{type-name}/{instance-uuid}/contexts") @Produces("application/json;charset=UTF-8") public String getInstanceContexts(@PathParam("type-name") String type, @PathParam("instance-uuid") String instanceId) throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves the list of contexts where a specific instance is present in the Resource Registry. REST Endpoint: GET /access/instances/{type-name}/{instance-uuid}/contexts Request Examples:
      • Get contexts for a resource: GET /access/instances/EService/48af15ad-7e56-4157-b624-71c98cea4f8f/contexts
      • Get contexts for a facet: GET /access/instances/ContactFacet/4023d5b2-8601-47a5-83ef-49ffcbfc7d86/contexts.
      Path Parameters:
      • type-name: The name of the Information System type (e.g., "EService", "ContactFacet")
      • instance-uuid: The unique identifier of the instance whose contexts to retrieve.
      Query Parameters:
      • This endpoint does not accept any query parameters
      • No filtering, pagination, or metadata options are available.
      Authorization Requirements: IS-Manager:
      • Can retrieve context information for any instance
      • Full access to view contexts across the entire infrastructure.
      Infrastructure-Manager:
      • Can retrieve context information for any instance
      • Full access to view contexts across the entire infrastructure.
      Context-Manager:
      • Can retrieve context information for any accessible instance
      • Access depends on their Context-Manager role in relevant contexts.
      Other Users:
      • Can retrieve context information for any accessible instance
      • Access depends on their permissions and context availability through their token.
      Response Codes:
      • 200 OK: Context list successfully retrieved
      • 404 Not Found: Instance does not exist
      • 403 Forbidden: Instance exists but is available in another context (not accessible for context listing).
      Response Format:
      • Returns a JSON object containing the contexts where the instance is present
      • Each key is a context UUID and each value is the current full context path
      • Empty object is returned if the instance exists but is not present in any contexts.
      Example Response: ``json { "3d846e2f-3582-4344-b03a-629d4cd34d53": "/gcube/devsec/devVRE", "4eb849d5-efbb-4430-9eb6-1968123921b4": "/gcube", "a7bc333f-84df-498d-ae9d-748b358267b5": "/gcube/devsec" } ``
      Parameters:
      type - The name of the Information System type
      instanceId - The unique identifier of the instance
      Returns:
      JSON object containing context UUID to context path mappings where the instance is present
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval

    • graphQuery

      @GET @Path("query") @Produces("application/json;charset=UTF-8") public String graphQuery(@QueryParam("q") String query, @QueryParam("raw") @DefaultValue("false") Boolean raw) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException
      Executes a graph query directly against the Resource Registry backend database. REST Endpoint: GET /access/query?q={raw-query}[&raw={true|false}] ⚠️ PRODUCTION WARNING:
      • ⚠️ NOT FOR PRODUCTION USE: This endpoint is intended for development, debugging, and administrative purposes only
      • ⚠️ NO COMPATIBILITY GUARANTEE: The query syntax and behavior may change without notice
      • ⚠️ BACKEND DEPENDENCY: Currently based on OrientDB which may be replaced at any time without prior warning
      • ⚠️ BREAKING CHANGES: Future backend changes will break existing queries without migration support
      • ⚠️ USE AT YOUR OWN RISK: Production applications should use type-specific endpoints instead.
      Request Examples:
      • Basic vertex query: GET /access/query?q=SELECT FROM V
      • Count resources: GET /access/query?q=SELECT count(*) FROM Resource
      • Raw backend response: GET /access/query?q=SELECT FROM EService&raw=true
      • With pagination: GET /access/query?q=SELECT FROM EService SKIP 10 LIMIT 20
      • Complex query: GET /access/query?q=SELECT FROM EService WHERE out('ConsistsOf').@class = 'StateFacet'
      • With metadata (raw=false): GET /access/query?q=SELECT FROM EService&includeMeta=true
      • Hierarchical (admin only): GET /access/query?q=SELECT FROM EService&hierarchical=true.
      Query Parameters: q (required):
      • The OrientDB SQL query to execute against the backend
      • Must be URL-encoded for special characters
      • Only idempotent queries are accepted (SELECT statements)
      • For query syntax reference: OrientDB SQL Documentation
      • Example: ?q=SELECT FROM EService WHERE out('ConsistsOf').@class = 'StateFacet'.
      raw (optional): Whether to return the raw backend response or format it according to the Information System model.
      • Default value: false (format results according to IS model)
      • Values: true|false
      • When false: Results are converted to standard Information System model format with proper typing and structure
      • When true: Results are returned exactly as provided by the OrientDB backend without any formatting or conversion
      • Example: ?raw=true (returns raw OrientDB response format).
      polymorphic (optional, when raw=false): Whether to include instances of subtypes both main type instance as well as nested instances.
      • Default value: true (includes all subtypes both main type instance as well as nested instances)
      • Values: true|false
      • Only effective when raw=false (ignored when raw=true)
      • Example: ?polymorphic=false (exact type matching both main type instance as well as nested instances).
      includeMeta (optional, when raw=false): Whether to include metadata in the response instances.
      • Default value: false (basic information only)
      • Values: true|false
      • Only effective when raw=false (ignored when raw=true)
      • Example: ?includeMeta=true (includes complete metadata for admin users).
      allMeta (optional, when raw=false): Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.).
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main instances)
      • Values: true|false
      • Only effective when raw=false (ignored when raw=true)
      • Example: ?includeMeta=true&allMeta=true (includes metadata for all nested elements).
      hierarchical (optional, admin-only): Whether to execute the query across child contexts of the current context.
      • Default value: false (current context only)
      • Values: true|false
      • Restriction: Only available to IS-Manager and Infrastructure-Manager roles
      • Example: ?hierarchical=true (executes query in current and child contexts)
      • When raw=true: Only this parameter is checked (other boolean parameters ignored)
      • When raw=false: All boolean parameters are validated and applied.
      includeContexts (optional, when raw=false): Whether to include the list of contexts where each returned instance is available.
      • Default value: false (context information not included)
      • Values: true|false
      • Only effective when raw=false (ignored when raw=true)
      • Example: ?includeContexts=true (shows context availability for each instance).
      Authorization Requirements: IS-Manager:
      • Full access to execute any graph query
      • Can use hierarchical querying across all contexts
      • Receives complete, unfiltered metadata when raw=false and includeMeta=true
      • Can access raw backend responses when raw=true.
      Infrastructure-Manager:
      • Full access to execute any graph query
      • Can use hierarchical querying across all contexts
      • Receives complete, unfiltered metadata when raw=false and includeMeta=true
      • Can access raw backend responses when raw=true.
      Infrastructure-Manager:
      • Full access to execute any graph query
      • Can use hierarchical querying across all contexts
      • Receives complete, unfiltered metadata when raw=false and includeMeta=true
      • Can access raw backend responses when raw=true.
      Operation Behavior:
      • Query Validation: Only idempotent SELECT queries are accepted; INSERT/UPDATE/DELETE operations are rejected
      • Pagination Responsibility: Client must handle pagination using OrientDB SQL SKIP and LIMIT clauses
      • Context Scope: Queries execute within the current context unless hierarchical=true is specified by authorized users
      • Response Format: Depends on raw parameter - either OrientDB native format or Information System model format
      • Performance: Raw queries may be faster but sacrifice type safety and model consistency.
      Response Codes:
      • 200 OK: Query successfully executed
      • 400 Bad Request: Invalid query syntax or non-idempotent query attempted
      • 403 Forbidden: Insufficient permissions to execute graph queries (only IS-Manager and Infrastructure-Manager allowed).
      Response Format:
      • When raw=false: JSON array containing instances formatted according to Information System model with proper typing, metadata (if requested), and context information (if requested)
      • When raw=true: JSON response exactly as returned by the OrientDB backend without any formatting or model conversion
      • Empty array/response is returned if no results match the query criteria.
      Parameters:
      query - The OrientDB SQL query to execute (must be idempotent SELECT statement)
      raw - Whether to return raw backend response (true) or Information System model formatted response (false)
      Returns:
      JSON containing query results - either raw OrientDB format or IS model format based on raw parameter
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the query is invalid, not idempotent, or contains syntax errors

    • jsonQuery

      @POST @Path("query") public String jsonQuery(String jsonQuery) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Executes a JSON-based query to find instances matching the specified structure in the Resource Registry. REST Endpoint: POST /access/query Request Examples:
      • Basic JSON query: POST /access/query
      • With pagination: POST /access/query?limit=20&offset=40
      • With subtypes and metadata: POST /access/query?polymorphic=true&includeMeta=true
      • Full metadata context: POST /access/query?includeMeta=true&amp;allMeta=true
      • With context information: POST /access/query?includeContexts=true
      • Hierarchical (admin only): POST /access/query?hierarchical=true
      • Hierarchical with contexts (admin only): POST /access/query?hierarchical=true&includeContexts=true.
      Request Body:
      • JSON object describing the structure to search for
      • Must specify the target type and optionally its relations and properties
      • Relations can include ConsistsOf, IsRelatedTo, and other defined relation types
      • Properties can specify exact values or patterns to match.
      Example Request Body - Find EService with specific state and software: ``json { "type": "EService", "consistsOf": [ { "type": "ConsistsOf", "propagationConstraint": { "add": "propagate" }, "target": { "type": "StateFacet", "value": "down" } }, { "type": "IsIdentifiedBy", "target": { "type": "SoftwareFacet", "name": "data-transfer-service", "group": "DataTransfer" } } ] } ` <strong>Query Parameters:</strong> <strong>polymorphic</strong> (optional): Whether to include instances of subtypes in the response and nested relations. <ul> <li>Default value: true (includes all subtypes)</li> <li>Values: true|false</li> <li>Example: ?polymorphic=false (returns only exact type instances).</li> </ul> <strong>limit</strong> (optional): <ul> <li>Maximum number of instances to return in a single response</li> <li>Default value: 10</li> <li>Example: ?limit=50 (returns at most 50 instances).</li> </ul> <strong>offset</strong> (optional): <ul> <li>Number of instances to skip from the beginning of the result set</li> <li>Default value: 0 (starts from the first instance)</li> <li>Example: ?offset=100 (skips the first 100 instances).</li> </ul> <strong>includeMeta</strong> (optional): Whether to include metadata in the response instances. <ul> <li>Default value: false (basic information only)</li> <li>Values: true|false</li> <li>Example: ?includeMeta=true (includes metadata with appropriate filtering based on user role)</li> <li>Metadata includes only the requested type and subtypes (if polymorphic=true)</li> <li><strong>Restriction:</strong> IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.</li> </ul> <strong>allMeta</strong> (optional): Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.). <ul> <li>Must be used in conjunction with includeMeta=true</li> <li>Default value: false (metadata only for main instances, more human-readable)</li> <li>Values: true|false</li> <li>Example: ?includeMeta=true&amp;allMeta=true (includes metadata for all nested elements)</li> <li>Purpose: When false, produces more human-readable responses with less JSON to process.</li> </ul> <strong>hierarchical</strong> (optional, admin-only): Whether to include instances from child contexts of the current context. <ul> <li>Default value: false (current context only)</li> <li>Values: true|false</li> <li><strong>Restriction:</strong> Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles (Context-Manager must be of the current context derived from the authorization token)</li> <li>Example: ?hierarchical=true (includes instances from current and child contexts)</li> <li>Current context is determined from the authorization token.</li> </ul> <strong>includeContexts</strong> (optional): Whether to include the list of contexts where each instance is available. <ul> <li>Default value: false (context information not included)</li> <li>Values: true|false</li> <li>Example: ?includeContexts=true (shows context availability for each instance)</li> <li><strong>Note:</strong> A Resource is present in all contexts that form the union of contexts of all its Facets</li> <li><strong>Note:</strong> ConsistsOf relations are present in all contexts where their target Facets are present.</li> </ul> <strong>Authorization Requirements:</strong> <strong>IS-Manager:</strong> <ul> <li>Full access to execute any JSON query</li> <li>Can use hierarchical querying across all contexts</li> <li>Receives complete, unfiltered metadata including all administrative fields.</li> </ul> <strong>Infrastructure-Manager:</strong> <ul> <li>Full access to execute any JSON query</li> <li>Can use hierarchical querying across all contexts</li> <li>Receives complete, unfiltered metadata including all administrative fields.</li> </ul> <strong>Context-Manager:</strong> <ul> <li>Can execute JSON queries with hierarchical querying within their managed context hierarchy</li> <li>Must be Context-Manager of the current context (derived from the authorization token)</li> <li>Receives complete, unfiltered metadata including all administrative fields.</li> </ul> <strong>Other Users:</strong> <ul> <li>Can execute JSON queries in the current context only</li> <li>Cannot use hierarchical querying (hierarchical parameter ignored)</li> <li>Receive metadata with sensitive information filtered when includeMeta=true.</li> </ul> <strong>Operation Behavior:</strong> <ul> <li><strong>Structure Matching</strong>: The JSON query describes the structure to match - instances must have the specified properties and relations</li> <li><strong>Flexible Matching</strong>: Properties not specified in the query are ignored; only specified properties must match</li> <li><strong>Relation Traversal</strong>: ConsistsOf and IsRelatedTo relations are traversed to find matching nested structures</li> <li><strong>Type Polymorphism</strong>: When polymorphic=true, subtypes are included in both main results and nested relations</li> <li><strong>Pagination Support</strong>: Results can be paginated using limit and offset parameters</li> <li><strong>Context Scope</strong>: Queries execute within the current context unless hierarchical=true is specified by authorized users.</li> </ul> <strong>Response Codes:</strong> <ul> <li><strong>200 OK</strong>: JSON query successfully executed</li> <li><strong>400 Bad Request</strong>: Invalid query structure, syntax errors, or invalid parameters</li> <li><strong>403 Forbidden</strong>: Insufficient permissions to execute JSON queries or access hierarchical data.</li> </ul> <strong>Response Format:</strong> <ul> <li>Returns a JSON array containing instances that match the query structure</li> <li>Each instance includes its properties, relations, and metadata (if requested)</li> <li>Empty array is returned if no instances match the specified structure in the accessible contexts.</li> </ul> <strong>Example Metadata (filtered for non-admin users):</strong> `json "metadata": { "type": "Metadata", "creationTime": "2025-03-18 17:13:40.952 +0100", "createdBy": "HIDDEN_FOR_PRIVACY", "lastUpdateBy": "HIDDEN_FOR_PRIVACY", "lastUpdateTime": "2025-03-19 16:21:16.805 +0100" } ``
      Parameters:
      jsonQuery - JSON object describing the structure to search for
      Returns:
      JSON array containing instances that match the query structure with their properties and relations
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the provided query structure is invalid or contains syntax errors
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if there is an error in the resource registry during query execution

    • getAllResourcesHavingFacet

      @GET @Path("query/{resource-type-name}/{relation-type-name}/{reference-type-name}") @Produces("application/json;charset=UTF-8") public String getAllResourcesHavingFacet(@PathParam("resource-type-name") String resourceTypeName, @PathParam("relation-type-name") String relationTypeName, @PathParam("reference-type-name") String referenceTypeName, @QueryParam("_reference") String reference, @QueryParam("_polymorphic") @DefaultValue("false") Boolean polymorphic, @QueryParam("_direction") @DefaultValue("out") String direction, @Context jakarta.ws.rs.core.UriInfo uriInfo) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Executes a prepared query to find resources connected to specific entities through defined relations. This method provides a structured way to query the Resource Registry using path and query parameters. REST Endpoint: GET /access/query/{resource-type-name}/{relation-type-name}/{reference-type-name} Request Examples:
      • All EServices identified by a SoftwareFacet: GET /access/query/EService/IsIdentifiedBy/SoftwareFacet?_polymorphic=true&_direction=out
      • All EServices identified by specific SoftwareFacet: GET /access/query/EService/IsIdentifiedBy/SoftwareFacet?_reference=7bc997c3-d005-40ff-b9ed-c4b6a35851f1&_polymorphic=true&_direction=out
      • All Resources with a ContactFacet: GET /access/query/Resource/ConsistsOf/ContactFacet?_polymorphic=true&_direction=out
      • All EServices hosted by HostingNodes: GET /access/query/EService/Hosts/HostingNode?_polymorphic=true&_direction=in
      • All EServices hosted by specific HostingNode: GET /access/query/EService/Hosts/HostingNode?_reference=16032d09-3823-444e-a1ff-a67de4f350a8&_polymorphic=true&_direction=in
      • With pagination: GET /access/query/EService/IsIdentifiedBy/SoftwareFacet?_polymorphic=true&_direction=out&limit=20&offset=40
      • With metadata: GET /access/query/EService/IsIdentifiedBy/SoftwareFacet?_polymorphic=true&_direction=out&includeMeta=true
      • Hierarchical (admin only): GET /access/query/EService/IsIdentifiedBy/SoftwareFacet?_polymorphic=true&_direction=out&hierarchical=true.
      Path Parameters:
      • resource-type-name: The name of the Resource type to search for (e.g., "EService", "HostingNode", "Software")
      • relation-type-name: The name of the relation connecting resources to entities (e.g., "IsIdentifiedBy", "ConsistsOf", "Hosts")
      • reference-type-name: The name of the Resource/Facet type connected through the relation (e.g., 'SoftwareFacet', 'ContactFacet', 'EService', 'HostingNode').
      Query Parameters: _polymorphic (optional): Whether to include instances of subtypes in the response and nested relations.
      • Default value: false (exact type matching only)
      • Values: true|false
      • Example: ?_polymorphic=true (includes all subtypes).
      _direction (optional):
      • Direction of the relation traversal from the resource perspective
      • Default value: out (outgoing relations from resource)
      • Values: out|in
      • out: Resources having outgoing relations to the specified entity type (e.g., Resource ConsistsOf Facet)
      • in: Resources having incoming relations from the specified entity type (e.g., EService hosted by HostingNode)
      • Example: ?_direction=in (incoming relations).
      _reference (optional):
      • UUID of a specific entity instance to filter by
      • When specified: only resources connected to that specific entity instance are returned
      • When not specified: resources connected to any entity of the specified type are returned
      • Must be a valid UUID format
      • Example: ?_reference=7bc997c3-d005-40ff-b9ed-c4b6a35851f1.
      Additional Constraint Parameters (optional):
      • Any other query parameters are treated as property constraints on the connected entities
      • Parameter names must match property names in the target entity type
      • Only entities with matching property values will be considered
      • Example: ?name=data-transfer-service&group=DataTransfer (filters SoftwareFacet by name and group).
      Standard Query Parameters (same as JSON query): limit (optional):
      • Maximum number of resources to return in a single response
      • Default value: 10
      • Example: ?limit=50 (returns at most 50 resources).
      offset (optional):
      • Number of resources to skip from the beginning of the result set
      • Default value: 0 (starts from the first resource)
      • Example: ?offset=100 (skips the first 100 resources).
      polymorphic (optional, different from _polymorphic): Whether to include instances of subtypes in nested relations within returned resources.
      • Default value: true (includes all subtypes in nested relations)
      • Values: true|false
      • Example: ?polymorphic=false (exact type matching in nested relations).
      includeMeta (optional): Whether to include metadata in the response resources.
      • Default value: false (basic information only)
      • Values: true|false
      • Example: ?includeMeta=true (includes metadata with appropriate filtering based on user role)
      • Metadata includes only the requested type and subtypes (if polymorphic=true)
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (optional): Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.).
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main resources, more human-readable)
      • Values: true|false
      • Example: ?includeMeta=true&allMeta=true (includes metadata for all nested elements)
      hierarchical (optional, admin-only): Whether to include resources from child contexts of the current context.
      • Default value: false (current context only)
      • Values: true|false
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles (Context-Manager must be of the current context derived from the authorization token)
      • Example: ?hierarchical=true (includes resources from current and child contexts).
      includeContexts (optional): Whether to include the list of contexts where each resource is available.
      • Default value: false (context information not included)
      • Values: true|false
      • Example: ?includeContexts=true (shows context availability for each resource).
      Authorization Requirements: IS-Manager:
      • Full access to execute any prepared query
      • Can use hierarchical querying across all contexts
      • Receives complete, unfiltered metadata including all administrative fields
      Infrastructure-Manager:
      • Full access to execute any prepared query
      • Can use hierarchical querying across all contexts
      • Receives complete, unfiltered metadata including all administrative fields.
      Context-Manager:
      • Can execute prepared queries with hierarchical querying within their managed context hierarchy
      • Must be Context-Manager of the current context (derived from the authorization token)
      • Receives complete, unfiltered metadata including all administrative fields.
      Other Users:
      • Can execute prepared queries in the current context only
      • Cannot use hierarchical querying (hierarchical parameter ignored)
      • Receive metadata with sensitive information filtered when includeMeta=true.
      Operation Behavior:
      • Prepared Query Pattern: Uses path parameters to define the query structure (resource-relation-entity pattern)
      • Relation Traversal: Follows the specified relation in the given direction to find connected resources
      • Constraint Application: Additional query parameters are applied as property filters on the target entities
      • Type Validation: Resource type must be a valid Resource type; relation and entity types must exist in the model
      • Reference Filtering: When _reference is specified, only resources connected to that specific entity instance are returned
      • Pagination Support: Results can be paginated using limit and offset parameters
      • Context Scope: Queries execute within the current context unless hierarchical=true is specified by authorized users.
      Response Codes:
      • 200 OK: Prepared query successfully executed
      • 400 Bad Request: Invalid resource type, relation type, entity type, UUID format, or query parameters
      • 403 Forbidden: Insufficient permissions to execute prepared queries or access hierarchical data
      • 404 Not Found: Specified types do not exist in the model.
      Response Format:
      • Returns a JSON array containing resources that match the prepared query criteria
      • Each resource includes its properties, relations, and metadata (if requested)
      • Empty array is returned if no resources match the specified criteria in the accessible contexts
      • Resources are returned with their complete structure based on polymorphic and metadata settings.
      Example Metadata (filtered for non-admin users): ``json "metadata": { "type": "Metadata", "creationTime": "2025-03-18 17:13:40.952 +0100", "createdBy": "HIDDEN_FOR_PRIVACY", "lastUpdateBy": "HIDDEN_FOR_PRIVACY", "lastUpdateTime": "2025-03-19 16:21:16.805 +0100" } ``
      Parameters:
      resourceTypeName - The name of the Resource type to search for
      relationTypeName - The name of the relation connecting resources to entities
      referenceTypeName - The name of the Entity/Facet type connected through the relation
      reference - UUID of a specific entity instance to filter by (optional)
      polymorphic - Whether to include subtypes in the main query (default: false)
      direction - Direction of relation traversal (out|in, default: out)
      uriInfo - URI information containing additional constraint parameters
      Returns:
      JSON array containing resources that match the prepared query criteria
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if there is an error during query execution, invalid types, or invalid parameters