docs/api_guide.md

API Guide

The Tensorus Metadata System provides a comprehensive RESTful API for managing and interacting with tensor metadata.

Interactive API Documentation (Swagger UI)

The API is self-documenting using OpenAPI. Once the application is running (e.g., locally at http://localhost:7860), you can access the interactive Swagger UI at:

• /docs: http://localhost:7860/docs

This interface allows you to explore all available endpoints, view their request and response schemas, and even try out API calls directly from your browser.

Alternative API Documentation (ReDoc)

An alternative ReDoc interface is also available at:

• /redoc: http://localhost:7860/redoc

Main API Categories

The API is organized into several categories based on functionality:

• Tensor Descriptors: Core operations for creating, reading, updating, deleting, and listing tensor descriptors.
• Semantic Metadata (Per Tensor): Managing human-readable names, descriptions, etc., associated with specific tensors, nested under /tensor_descriptors/{tensor_id}/semantic/.
• Extended Metadata (Per Tensor): CRUD operations for detailed metadata types, nested under /tensor_descriptors/{tensor_id}/:
  • Lineage Metadata (/lineage)
  • Computational Metadata (/computational)
  • Quality Metadata (/quality)
  • Relational Metadata (/relational)
  • Usage Metadata (/usage)
• Versioning & Lineage: Endpoints for creating tensor versions and managing lineage relationships at a higher level.
• Search & Aggregation: Advanced querying, text-based search across metadata, and metadata aggregation.
• Import/Export: Endpoints for exporting and importing tensor metadata in JSON format.
• Management: Health checks and system metrics.
• Authentication: Write operations (POST, PUT, PATCH, DELETE) are protected by API keys. See Installation and Configuration for details on setting API keys. The API key should be passed in the HTTP header specified by TENSORUS_API_KEY_HEADER_NAME (default: X-API-KEY).

Please refer to the interactive /docs for detailed information on each endpoint, including request parameters, request bodies, and response structures.