API Reference Overview¶

The Dataspace Ecosystem exposes several REST APIs for management and runtime operations. This page covers the overall API structure, common patterns, authentication, and how APIs relate to the system architecture.

API Structure¶

graph LR
    Client --> CP[Control Plane APIs]
    Client --> DP[Data Plane APIs]
    Client --> IH[Identity APIs]

    subgraph ControlPlane[Control Plane]
        CP --> Management[Management API]
        CP --> Protocol[Protocol API]
        CP --> Observability[Observability API]
    end

    subgraph DataPlane[Data Plane]
        DP --> Public[Public API]
        DP --> Control[Control API]
    end

    subgraph Identity[Identity]
        IH --> IdentityAPI[Identity API]
        IH --> Presentation[Presentation API]
    end

How APIs Map to Architecture¶

The table below maps each API to its architectural component, explaining what role it plays in the overall ecosystem. Use the architecture links to understand the component's design, and the API links to see endpoint details.

Typical End-to-End Workflow¶

The following sequence diagram shows the complete happy-path flow from a consumer's perspective — from discovering data to receiving it. Each step indicates which API is involved.

sequenceDiagram
    participant Consumer as Consumer Application
    participant CPAPI as Control Plane API<br/>(Management)
    participant Protocol as Control Plane API<br/>(Protocol - Automatic)
    participant ProviderCP as Provider Control Plane
    participant IH as Identity Hub
    participant DPAPI as Data Plane API<br/>(Public)

    rect rgb(232, 245, 232)
        Note over Consumer,IH: Step 1: Identity & Onboarding
        Consumer->>IH: Request membership credential
        IH-->>Consumer: Credential issued
    end

    rect rgb(225, 245, 254)
        Note over Consumer,ProviderCP: Step 2: Discover Data
        Consumer->>CPAPI: POST /v3/catalog (query available datasets)
        CPAPI->>Protocol: Fetch catalog from provider (automatic)
        Protocol->>ProviderCP: DSP catalog request
        ProviderCP-->>Protocol: Catalog with assets, policies, offers
        Protocol-->>CPAPI: Catalog response
        CPAPI-->>Consumer: Available datasets and contract offers
    end

    rect rgb(225, 245, 254)
        Note over Consumer,ProviderCP: Step 3: Negotiate Contract
        Consumer->>CPAPI: POST /v3/contractnegotiations (initiate)
        CPAPI->>Protocol: Contract negotiation (automatic)
        Protocol->>ProviderCP: DSP negotiation messages
        ProviderCP->>IH: Verify consumer credentials
        IH-->>ProviderCP: Credentials verified
        ProviderCP-->>Protocol: Contract agreement
        Protocol-->>CPAPI: Agreement stored
        CPAPI-->>Consumer: Contract agreement ID
    end

    rect rgb(255, 243, 224)
        Note over Consumer,DPAPI: Step 4: Transfer Data
        Consumer->>CPAPI: POST /v3/transferprocesses (initiate transfer)
        CPAPI-->>Consumer: Transfer started + EDR token
        Consumer->>DPAPI: GET /data (with contract agreement headers)
        DPAPI-->>Consumer: Actual data
    end

Workflow Steps Explained¶

Available APIs¶

Authentication¶

API Key (Development)¶

curl -H "X-Api-Key: password" http://localhost:8181/management/v3/assets

OAuth 2.0¶

curl -H "Authorization: Bearer <token>" http://localhost:8181/management/v3/assets

Verifiable Credentials¶

For protocol endpoints, authentication uses verifiable credentials and DID resolution.

Common Patterns¶

Request Format¶

All APIs use JSON-LD:

{
  "@context": {
    "@vocab": "https://w3id.org/edc/v0.0.1/ns/",
    "odrl": "http://www.w3.org/ns/odrl/2/"
  },
  "@type": "Asset",
  "@id": "asset-1",
  "properties": {
    "name": "My Asset"
  }
}

Response Format¶

{
  "@context": {
    "@vocab": "https://w3id.org/edc/v0.0.1/ns/"
  },
  "@type": "Asset",
  "@id": "asset-1",
  "createdAt": 1705312000000,
  "properties": {
    "name": "My Asset"
  }
}

Error Response¶

{
  "@type": "ApiErrorDetail",
  "message": "Asset not found",
  "type": "NOT_FOUND",
  "path": "/management/v3/assets/unknown-id",
  "invalidValue": "unknown-id"
}

Pagination¶

{
  "@context": { ... },
  "querySpec": {
    "offset": 0,
    "limit": 50,
    "sortField": "createdAt",
    "sortOrder": "DESC"
  }
}

Filtering¶

{
  "querySpec": {
    "filterExpression": [
      {
        "operandLeft": "asset:prop:type",
        "operator": "=",
        "operandRight": "data"
      }
    ]
  }
}

HTTP Status Codes¶

OpenAPI Specifications¶

OpenAPI specs are available at:

• Control Plane: http://localhost:8181/api/management/openapi.yaml
• Data Plane: http://localhost:8383/api/public/openapi.yaml

API Versioning¶

APIs are versioned in the URL path:

• Current: /v3/
• Legacy: /v2/ (deprecated)

Rate Limiting¶

Production deployments may include rate limiting:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705315600

See Also¶

• Control Plane API
• Data Plane API
• Identity API
• Architecture Index — Understand how components and APIs relate
• System Overview — High-level architecture diagram