***************************************************
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**

.. raw:: html

   <table border="1" class="docutils">
   <colgroup>
   <col width="30%" />
   <col width="70%" />
   </colgroup>
   <thead valign="bottom">
   <tr><th>Resource</th>
   <th>Description</th>
   </tr>
   </thead>
   <tbody valign="top">
   <tr><td><strong>Service Documentation</strong></td>
   <td>You are here - Complete Service Documentation</td>
   </tr>
   <tr><td><strong>API Documentation</strong></td>
   <td><a href="../api-docs/index.html" target="_blank">REST-API docs</a></td>
   </tr>
   <tr><td><strong>API Testing</strong></td>
   <td><a href="../api-docs/swagger.html" target="_blank">Swagger UI</a></td>
   </tr>
   <tr><td><strong>OpenAPI Specification</strong></td>
   <td><a href="../api-docs/openapi.json" target="_blank">openapi.json</a></td>
   </tr>
   </tbody>
   </table>

=============
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 <#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 <../api-docs/index.html>`_ for full details, test the APIs directly from your browser using the `Swagger UI interface <../api-docs/swagger.html>`_, and download the machine-readable OpenAPI specification as `openapi.json <../api-docs/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) <https://openid.net/connect>`_ 
for authentication and UMA 2 (User-Managed Authorization) for authorization flows. 
`JSON Web Token (JWT) Access tokens <https://jwt.io/>`_ 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.


.. table::

  +--------------+-------------+----------------------------------------+---------------------+--------+------------+
  |  Operation   | HTTP Method | URL                                    | Success HTTP Status |  Safe  | Idempotent |
  +==============+=============+========================================+=====================+========+============+
  | Supported    | OPTIONS     | /{collection}                          | 204 No Content      |   Y    |     Y      |
  | HTTP Methods |             |                                        | [#allow]_           |        |            |
  +--------------+-------------+----------------------------------------+---------------------+--------+------------+
  | 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    | OPTIONS     | /{collection}/{instance-id}            | 204 No Content      |   Y    |     Y      |
  | HTTP Methods |             |                                        | [#allow]_           |        |            |
  +--------------+-------------+----------------------------------------+---------------------+--------+------------+
  | 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 [#del]_ |
  +--------------+-------------+----------------------------------------+---------------------+--------+------------+
  | Purge        | DELETE      | /{collection}/{instance-id}?purge=true | 204 No Content      |   N    |  N [#del]_ |
  +              +-------------+----------------------------------------+---------------------+--------+------------+
  |              | PURGE       | /{collection}/{instance-id}            | 204 No Content      |   N    |  N [#del]_ |
  +--------------+-------------+----------------------------------------+---------------------+--------+------------+

.. [#allow] Supported HTTP Methods in **Allow** HTTP Header
  
.. [#del] DELETE has been defined as idempotent.
  
  *Allamaraju* [#Allamaraju]_ 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.

.. [#Allamaraju] 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 <https://varnish-cache.org/docs/3.0/tutorial/purging.html>`_, 
  `Squid <https://wiki.squid-cache.org/SquidFaq/OperatingSquid#How_can_I_purge_an_object_from_my_cache.3F>`_).
  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. 

.. code-block:: rest

  Accept: application/json

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

.. code-block:: rest

  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 
<https://support.d4science.org>`_. 

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:**

.. code-block:: xml

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

**Basic Usage Example:**

.. code-block:: java

    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 <../api-docs/index.html>`_ 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:

.. code:: javascript

  {
      ....
  }

*Inputs are automatically validated before the request is served.*

================
Examples
================

**Creating a Service Resource:**

.. code-block:: rest

    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:**

.. code-block:: rest

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

**Adding Resource to Context:**

.. code-block:: rest

    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.

