====================
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.
