Resource Registry Service - Documentation¶

The Resource Registry is a RESTful web service that represents the core component of the gCube Information System. This service provides persistence and management of gCube infrastructure resources using a graph-based model.

Overview¶

The Resource Registry manages a graph of entities and relationships representing resources and facets, along with their connections. Contexts provide a hierarchically organized visibility layer that controls access to these graph entities. The service uses OrientDB as the underlying database and provides REST APIs for complete CRUD operations on all elements of the information model.

Academic Reference:

For the theoretical foundations and detailed design rationale of the gCube Information System (of which the Resource Registry is the core component), see: Frosini, L. (2019). Transactional REST Information System for Federated Research Infrastructures enabling Virtual Research Environments. Università degli Studi di Pisa. https://doi.org/10.5281/zenodo.7464022

Key Features:

Context Management: Operations to create and manage hierarchical gCube contexts;
Type Management: Schema and type definition management with inheritance hierarchies;
Graph Entity Management: Unified CRUD operations for resources, facets, and their relationships (IsRelatedTo, ConsistsOf), including context sharing capabilities;
Schema Validation: Automatic compliance checking against defined types;
Advanced Queries: Support for prepared queries, JSON queries and query templates.

Quick Links¶

Documentation and API Access

Resource	Description
Service Documentation	You are here - Complete Service Documentation
API Documentation	REST-API docs
API Testing	Swagger UI
OpenAPI Specification	openapi.json

Architecture¶

The service is based on SmartGears 4 and uses:

JAX-RS: For REST API exposure;
OrientDB: As graph database for persistence;
gCube Jackson: For JSON serialization/deserialization (repackaged version of Jackson library);
gCube Security Framework: For authentication and authorization.

Data Model¶

The Resource Registry manages a graph-based data model that represents the gCube Information System Model. The graph consists of instances of entities (Resources and Facets) connected by instances of relationships (IsRelatedTo and ConsistsOf). Contexts provide a visibility and access control layer over this graph.

Model Characteristics:

Resource-Centric Design: The model is fundamentally resource-centric, where Resources represent infrastructure components that need to be managed;
Facet-Based Resource Description: Resources are described through Facets, which provide specific aspects of the resource (metadata, configurations, states, etc.). This approach is also known as the Facet Based Resource Model;
Semantic Relationships: ConsistsOf relationships connect Resources to their descriptive Facets, providing semantic meaning to each facet’s role in describing the resource;
Resource Interactions: IsRelatedTo relationships capture interactions and dependencies between different Resources in the infrastructure.

Graph Model Components¶

The Resource Registry provides a set of base types that serve as the foundation for extending and defining custom information models. These base types can be specialized through inheritance to create domain-specific models that meet particular infrastructure requirements.

The gCube Model represents a comprehensive example of how these base types can be extended to create a complete information model for research infrastructure management.

Important: It is the instances of the extended types (not the base types themselves) that form the knowledge graph stored in the Information System. The base types provide the structural foundation, while the extended types define the specific semantics and properties needed for actual resource management.

Entities¶

Resource Base type representing an infrastructure resource (services, datasets, software, etc.). Resources are the main entities that describe “things” to be managed in the infrastructure. This base type must be extended to create specific resource types with domain-specific properties and validation rules.

Facet Base type representing an aspect or characteristic of a resource (metadata, configurations, states, etc.). Facets contribute to “build” a description of a Resource. This base type must be extended to create specific facet types that capture particular aspects of resources.

Relationships¶

IsRelatedTo Base relationship type that connects resources to each other (dependencies, usage, hosting, etc.). This relationship captures the various interactions between resources. Must be extended to create specific relationship types with semantic meaning and domain-specific properties.

ConsistsOf Base relationship type that connects a resource to its facets. This relationship defines the characteristics and metadata of the resource. Every resource must have at least one facet. While in some cases it may be sufficient to create instances of the base ConsistsOf type, the type can be extended to create specific composition relationships with semantic constraints and validation rules.

Context Concept¶

Context is a fundamental visibility and access control mechanism within the gCube Information System. Unlike Resources and Facets, Context is NOT a graph entity but rather an organizational and security boundary that controls access to graph entities and relationships.

Key Characteristics:

Visibility Layer: Contexts define which entities and relationships are visible and accessible to users and services;
Hierarchical Organization: Contexts are organized in hierarchical structures that reflect organizational and access boundaries (e.g., Infrastructure → VO (Gateway) → VRE);

Note: The system does not enforce a maximum of three levels or require a single root. In practice, this three-level hierarchy represents the typical usage pattern for which gCube was designed. Different organizations adopting this technology could choose to use more or fewer levels and/or not leverage the hierarchical structure at all.
Not Graph Entities: Contexts are not part of the graph structure itself but overlay it as access control boundaries;
Membership Control: Every graph entity (Resource, Facet) and relationship (ConsistsOf, IsRelatedTo) belongs to one or more contexts;
Scope Definition: Contexts define the operational scope for queries, operations, and data access;
Hierarchical Visibility: Users with specific administrative roles can request visibility of instances from child contexts by explicitly enabling hierarchical parameters in read and query API calls.

Examples of Hierarchical Context Organization: - Infrastructure level: /gcube; - VO (Gateway) level: /gcube/devsec (child of /gcube); - VRE level: /gcube/devsec/devVRE (child of /gcube/devsec, descendant of /gcube).

This hierarchical organization allows users with appropriate administrative privileges to access instances from child contexts when operating in parent contexts (e.g., instances belonging to /gcube/devsec/devVRE can be accessed when operating in /gcube/devsec or /gcube) by explicitly requesting hierarchical visibility in API calls. The reverse is not possible: instances in parent contexts are not automatically accessible from child contexts. This provides controlled bottom-up visibility while maintaining strict context boundaries for regular users.

When an entity or relationship “belongs” to a context, it means it is visible and manageable within that context’s scope, but the context itself is not represented as a node or edge in the graph.

Service Capabilities and Features¶

The Resource Registry provides comprehensive infrastructure resource management through several key capabilities:

Context Management¶

Hierarchical Organization The service implements a sophisticated context hierarchy system that enables multi-level hierarchical structures. Contexts provide isolation and access control boundaries while supporting hierarchical visibility patterns.

Dynamic Context Operations Instances can be dynamically shared across contexts, enabling flexible collaboration models between different context levels (Infrastructure → VO (Gateway) → VRE) while maintaining security boundaries.

Hierarchical Visibility Users with appropriate administrative privileges can access entities from child contexts when operating in parent contexts through explicit hierarchical query parameters, providing controlled visibility across context boundaries.

Type System and Inheritance¶

Rich Type Definitions The service supports a comprehensive type system with inheritance hierarchies for Resources, Facets, and Relationships (IsRelatedTo, ConsistsOf). Types define structure, validation rules, and behavioral characteristics of all graph elements.

Type Inheritance Hierarchies All base types (Resource, Facet, IsRelatedTo, ConsistsOf) can be extended through inheritance to create specialized types with domain-specific properties and constraints. Child types inherit all properties and validation rules from their parent types while adding their own specific characteristics.

Dynamic Schema Evolution New types can be registered and existing types can be extended through inheritance, supporting the evolution of the information model without breaking existing data. This allows the schema to grow organically while maintaining backward compatibility.

Schema Validation All entity creation and modification operations are automatically validated against their defined types, ensuring data consistency and structural integrity. The validation includes both inherited and type-specific constraints.

Instance Management¶

Unified Entity Model Resources and Facets are managed through a unified instance management system that maintains their graph relationships (IsRelatedTo, ConsistsOf) while respecting context boundaries.

Polymorphic Operations All operations on graph instances (resources, facets, and relationships) support polymorphic behavior where subtypes are automatically included in queries and operations. This can be controlled through the polymorphic parameter, allowing both inclusive (default) and strict type matching. When polymorphic mode is enabled, querying for a parent type will automatically include all instances of its subtypes.

Relationship Integrity The service ensures referential integrity across all relationships while supporting complex operations like context sharing that maintain relationship consistency across multiple contexts.

Metadata Management All entities include comprehensive metadata (creation time, modification time, ownership) that is automatically managed by the service and can be filtered based on user authorization levels.

Cross-Context Instance Views Administrative users can request hierarchical views that aggregate instances from child contexts, providing consolidated views of resources across context boundaries.

Advanced Query Capabilities¶

The Resource Registry supports multiple sophisticated query mechanisms designed for different use cases:

Instance Listing Direct type-based listing with support for pagination, polymorphic inclusion, metadata control, and hierarchical context aggregation. Suitable for browsing and inventory operations.

JSON Structure Queries Declarative JSON-based queries that describe the desired structure and constraints. The service performs structure matching where graph elements must have the specified properties and relationships, with flexible constraint application.

Key JSON Query Features: - Structure Matching: Queries describe the desired graph pattern using JSON that mirrors the data model structure; - Flexible Constraints: Only specified properties and relationships need to match; unspecified elements are ignored; - Relation Traversal: Automatic traversal of IsRelatedTo and ConsistsOf relationships to find matching patterns; - Logical Operators: Support for complex constraints using logical operators (_and, _or, _not); - Comparison Operators: Rich set of comparison operators for property filtering (_eq, _neq, _gt, _gte, _lt, _lte, _like, _in, etc.); - Mathematical Operations: Support for mathematical operators (_sum, _minus, _multiply, etc.) to perform calculations on field values.

Projection and Field Selection: JSON queries support advanced projection capabilities through the _emit operator, allowing selection of specific fields rather than complete instances:

Field Projection: Select specific properties from graph instances rather than complete instances: (e.g., {"_emit": {"name": "Service Name", "version": "Version"}} projects only the name and version fields);
Custom Field Naming: Assign meaningful names to projected fields for enhanced result presentation: (e.g., {"_emit": {"name": "Service Name", "version": "Version"}} assigns custom labels “Service Name” and “Version” to the projected name and version fields).

Query Templates Parameterized JSON Queries that can be stored, reused, and executed with different parameter values. Templates support variable substitution (prefixed with $) and provide a library of common query patterns for frequent operations.

Prepared Queries Path-based queries using URL parameters to define resource-relation-entity patterns. These provide structured alternatives to free-form queries with built-in validation and type safety.

Graph Queries (Development/Debug) Direct OrientDB SQL queries for development and debugging purposes, available only to administrators. These queries come with explicit warnings about production use and compatibility. They provide maximum flexibility but sacrifice portability and safety.

Query Response Control¶

Context Information Optional inclusion of context information showing where each entity is available across the context hierarchy through the includeContexts parameter.

Pagination Support Comprehensive pagination support with limit and offset parameters for managing large result sets across all query types.

Response Format Control Control over response detail level and structure through parameters like polymorphic, includeMeta, allMeta, ensuring optimal response sizes for different use cases.

Metadata Inclusion Control Fine-grained control over metadata inclusion with role-based filtering: - Basic users receive filtered metadata with sensitive information obfuscated - Administrative users receive complete metadata including ownership and audit information - allMeta parameter controls metadata inclusion for nested elements

REST API Endpoints¶

The service exposes several groups of REST endpoints organized by functionality. All endpoints are relative to the service base URL.

Base Service URL: https://{host}/resource-registry

Endpoint Collections Overview¶

The Resource Registry API is organized into the following main collections:

Context Management (/contexts): Operations for creating and managing hierarchical gCube contexts (scopes), including context hierarchy management and resource associations. Contexts define the fundamental boundaries for all operations.
Type Management (/types): Schema and type definition management. Allows registration and management of new types and their inheritance hierarchies. Essential for defining the structure of resources and facets.
Instance Management (/instances): Unified CRUD operations for all graph entities and relationships. Handles creation, reading, updating, and deletion of resources, facets, and their relationships (IsRelatedTo, ConsistsOf). Every instance must conform to a defined type and belong to at least one context.
Sharing Operations (/sharing): Context-specific operations to add or remove resources from specific contexts, enabling resource sharing across different gCube environments. This extends the instance management capabilities with multi-context operations.
Query Templates (/query-templates): Management and execution of predefined query templates for common data access patterns.
Access Endpoints (/access): Read-only operations for querying and consulting existing data. This collection exposes read-only methods that are also available in other collections. The separation allows for enhanced network-level security by protecting modification APIs on different paths while keeping query operations openly accessible.

Important Conceptual Note: Every instance in the Information System is always of a defined type and belongs to at least one context. Types define the structure and validation rules, while contexts define visibility and access boundaries.

API Documentation¶

The complete REST API documentation is available online and provides detailed endpoint specifications, request/response examples, and interactive testing capabilities. You can browse the REST-API docs for full details, test the APIs directly from your browser using the Swagger UI interface, and download the machine-readable OpenAPI specification as openapi.json for use in tools like Postman, Insomnia, or for generating client SDKs. The documentation includes all HTTP methods, paths, parameters, request/response schemas with examples and validation rules, authentication integration for real-credential testing, and model definitions for all data types used in the API.

Authentication¶

D4Science adopts state-of-the-art industry standards for authentication and authorization. Specifically, the implementation fully adopts OIDC (OpenID Connect) for authentication and UMA 2 (User-Managed Authorization) for authorization flows. JSON Web Token (JWT) Access tokens are used for both authentication and authorization.

Obtain your Bearer token here: https://dev.d4science.org/how-to-access-resources

Context-based Access:

Access to resources is controlled by context (scope). Users can only see and manipulate resources within contexts they have access to. The current context is determined by the authorization token.

HTTP Methods¶

Resource Registry is a pure RESTful service. It uses standard HTTP Methods to perform a listing of collections and CRUD (Create Read Update Delete) operations on instances.

Operation	HTTP Method	URL	Success HTTP Status	Safe	Idempotent
Supported HTTP Methods	OPTIONS	/{collection}	204 No Content 1	Y	Y
List	GET	/{collection}	200 OK	Y	Y
Count	GET	/{collection}?count=true	200 OK	Y	Y
Exists	HEAD	/{collection}	204 No Content	Y	Y
Create	POST	/{collection}	201 Created	N	N
Supported HTTP Methods	OPTIONS	/{collection}/{instance-id}	204 No Content 1	Y	Y
Exist	HEAD	/{collection}/{instance-id}	204 No Content	Y	Y
Read	GET	/{collection}/{instance-id}	200 OK	Y	Y
Update	PUT	/{collection}/{instance-id}	200 OK	N	Y
Patch	PATCH	/{collection}/{instance-id}	200 OK	N	Y
Delete	DELETE	/{collection}/{instance-id}	204 No Content	N	N 2
Purge	DELETE	/{collection}/{instance-id}?purge=true	204 No Content	N	N 2
Purge	PURGE	/{collection}/{instance-id}	204 No Content	N	N 2

1(1,2)

Supported HTTP Methods in Allow HTTP Header

2(1,2,3)

DELETE has been defined as idempotent.

Allamaraju 3 argues that DELETE idempotency should be accomplished client-side. The server should inform the client if the delete operation succeeded because the resource was deleted or it was not found, i.e., 404 Not Found error is suggested instead of 204 No Content. The latter situation should be treated as idempotent by the client.

We share the same vision. For this reason, Resource Registry does not provide server-side idempotency for DELETE and PURGE operations.

3

Allamaraju S. RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity. O’Reilly. first ed. 2010

About URL¶

The presented URL uses the following convention:

{collection} is the plural name of the entity type;
{instance-id} is an identification that enables univocally identifying the instance in the collection.

About Safety and Idempotency properties¶

A method is Safe if it does not produce any side effects. “This does not prevent an implementation from including behaviour that is potentially harmful, that is not entirely read-only, or that causes side effects while invoking a safe method” https://tools.ietf.org/html/rfc7231#section-4.2.1;
A method is Idempotent if the same operation repeated multiple times has the same side effect as using it one time. “repeating the request will have the same intended effect, even if the original request succeeded, though the response might differ” https://tools.ietf.org/html/rfc7231#section-4.2.2.

You can find more information about HTTP Methods at https://restfulapi.net/http-methods/

Uncommon HTTP Methods¶

PATCH method allows to perform a differential update (i.e. an update which provides only the differences and not the whole new representation);
PURGE method is not a standard but is widely used in services that require this action (e.g. Varnish, Squid). Resource Registry provides support for this method, but to support a wider range of clients, it also provides the Purge action via DELETE with the additional get parameter purge=true.

Content-Type¶

Any request must contain an indication of the interesting content type.

The client must specify the Accept HTTP Header for any operation returning a result.

Accept: application/json

For any operation sending content to the service, it is necessary to specify the Content-Type HTTP Header.

Content-Type: application/json

The service accepts and returns only JSON objects.

Status Codes¶

The service returns standard HTTP status codes:

Success Codes: - 200 OK: Request successful, data returned; - 201 Created: Resource created successfully; - 204 No Content: Operation successful, no data returned (e.g., DELETE).

Client Error Codes: - 400 Bad Request: Invalid request format or parameters; - 401 Unauthorized: Missing or invalid authentication token; - 403 Forbidden: Insufficient permissions for the operation; - 404 Not Found: Requested resource does not exist; - 405 Method Not Allowed: The used HTTP method is not supported for the requested URL; - 409 Conflict: The request could not be completed due to a conflict with the current state of the target resource.

Server Error Codes: - 500 Internal Server Error: Unexpected server error; - 503 Service Unavailable: Service temporarily unavailable.

You can find a complete list of HTTP Status at https://httpstatuses.com/ or https://httpstatuses.io/

If you get a 500 Internal Server Error, please report it in the gCube ticketing system.

Please use this checklist before reporting an error:

Replicate the request;
The failure could be temporal due to a network error, a server issue, and many other temporal issues. For this reason, please retry the request after a certain amount of time before reporting the issue;
indicate how to replicate the error;
indicate the time when the error occurred (this simplifies identifying the issue).

Java Client Usage¶

The Resource Registry provides Java client libraries for easy integration.

Maven Dependency:

<dependency>
    <groupId>org.gcube.information-system</groupId>
    <artifactId>resource-registry-client</artifactId>
</dependency>

Basic Usage Example:

import org.gcube.informationsystem.resourceregistry.client.ResourceRegistryClient;
import org.gcube.informationsystem.resourceregistry.client.ResourceRegistryClientFactory;

// Get client instance
ResourceRegistryClient client = ResourceRegistryClientFactory.create();

// Read a resource
EService service = client.read(EService.class, uuid);

// Create a resource
EService newService = new EService();
// ... set facets ...
client.create(newService);

Methods Result:

The service exposes its methods using a standard naming approach. Moreover, they accept (in the case of HTTP POST/PUT methods) JSON objects.

Important

The result of all methods is always a JSON object as per below:

{
    ....
}

Inputs are automatically validated before the request is served.

Examples¶

Creating a Service Resource:

PUT /instances/EService/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
Authorization: Bearer your-oidc-token

{
    "type": "EService",
    "consistsOf": [
        {
            "type": "IsIdentifiedBy",
            "target": {
                "type": "SoftwareFacet",
                "group": "org.example",
                "name": "my-service",
                "version": "1.0.0"
            }
        },
        ...
    ]
}

Querying Resources:

GET /access/instances/EService?polymorphic=true&includeMeta=true

Adding Resource to Context:

PUT /sharing/contexts/{context-uuid}/EService/{resource-uuid}?operation=ADD

Best Practices¶

1. Use Appropriate Query Parameters: Always specify relevant parameters like polymorphic, includeMeta to optimize responses; 2. Context Management: Ensure proper context switching when working across multiple contexts (by switching the token); 3. Error Handling: Implement proper retry logic for 403 (Forbidden) errors which may indicate context issues; 4. Resource Relationships: Always validate Entities and Relationships (e.g. every Resource must have at least one Facet); 5. Schema Validation: Define proper types before creating instances to ensure data consistency.

Troubleshooting¶

Common Issues:

Authentication Errors (401/403): - Check token expiration and refresh if necessary; - Ensure the token has access to the target context.

Resource Not Found (404): - Verify the resource UUID and type are correct; - Check if the resource exists in the current context; - Use sharing endpoints to add the resource to your context.

Validation Errors (400): - Check JSON payload format and required fields; - Verify the resource conforms to its type schema; - Ensure all mandatory relationships are present.

Debugging Tips:

Include includeMeta=true to see creation and modification metadata;
Use access endpoints for read-only exploration;
Check the Postman collection for working examples.