# API Interactions

## Architecture Diagram

{% @mermaid/diagram content="sequenceDiagram
participant Client
participant API as Flashback API
participant Market as Market Service
participant Orch as Orchestrator
participant Adapter as Provider Adapter
participant Provider
participant Metrics as Metrics Service

```
Client->>API: GET /market/offerings
API->>Market: Query offerings
Market-->>API: Offerings list
API-->>Client: 200 Offerings

Client->>API: POST /allocations/reserve
API->>Market: Reserve Data Unit
Market->>Orch: Reservation event
Orch->>Adapter: Provision / allocate request
Adapter->>Provider: Allocate Data Unit
Provider-->>Adapter: Allocation confirmed
Adapter-->>Orch: Allocation result
Orch-->>API: Allocation status
API-->>Client: 202 Reserved / Allocating

Provider->>Metrics: Push telemetry
Orch->>Metrics: Pull metrics and health

Client->>API: GET /allocations/{id}
API->>Orch: Read allocation status
Orch-->>API: Status and routing details
API-->>Client: 200 Allocation status" %}
```

***

## **Oracles**

Oracles bridge on-chain and off-chain data by providing real-time verification signals to orchestrators (for example integrity checks, usage telemetry, pricing updates, and SLA evidence). They act as trusted validation intermediaries for service quality.

***

## **Suite API Model (Data Unit-Centric)**

The ISP Market no longer assumes one universal "standard API" for every resource type. Instead, API interactions are centered around the **allocated Data Unit** and its compatible access model.

* **Allocation-first flow**:
  * A Consumer selects and pays for a Data Unit in the marketplace.
  * After allocation, the platform generates credentials tied to that Data Unit.
* **Protocol compatibility by unit type**:
  * Storage Data Units can generate **S3-compatible keys** (and compatible endpoint details).
  * Other Data Unit categories can expose their own compatible access patterns through the Suite API layer.
* **Security scope**:
  * Credentials are scoped to the purchased allocation and lifecycle.
  * Access can be rotated/revoked based on policy, SLA state, or expiration.

This model gives Providers flexibility to expose resources with clear compatibility constraints, while giving Consumers an operational experience aligned with the selected unit.

***

## **Interactions Between Layers**

1. **Providers ↔ Suite APIs ↔ Orchestrator**:
   * Providers register Data Units and supported compatibility profiles.
   * The Orchestrator tracks lifecycle states and enforces policy conditions.
2. **Consumers ↔ Suite APIs ↔ Orchestrator**:
   * Consumers allocate and pay for a Data Unit.
   * The platform issues Data Unit-compatible credentials after successful allocation.
3. **Oracles ↔ Orchestrator ↔ Suite APIs**:
   * Oracles submit validated QoS/SLA evidence.
   * Orchestrator decisions can impact API access state (active, restricted, expired).

***

## **Practical Note for Storage Units**

For storage-focused Data Units, the default operational pattern is:

1. Select a storage Data Unit in ISP Market.
2. Purchase/allocate the Data Unit.
3. Receive generated S3-compatible credentials and endpoint details.
4. Interact directly with the allocated storage unit using these credentials.

As new Data Unit types are introduced, the same allocation-first principle applies, with compatibility determined by each unit profile.