Data Plane API¶

The Data Plane handles actual data transfer operations and is accessed through the API Gateway with consumer participant identifiers.

Base URL¶

{{protocol}}://{{apiGatewayHost}}/{{consumerId}}/dp

Data Access API¶

Access Data¶

After a successful transfer process initiation, consumers access data using the contract agreement ID:

GET /{{consumerId}}/dp/data
Contract-Id: {{contractAgreementId}}
Authorization: {{contractAgreementId}}

Access Data with Query Parameters¶

Route to specific sub-resources or filter data:

GET /{{consumerId}}/dp/data?start=2024-07-28T14:00:00&end=2024-07-29T20:00:00&limit=10
Contract-Id: {{contractAgreementId}}
Authorization: {{contractAgreementId}}

Query Parameters: - start: Start timestamp for data filtering - end: End timestamp for data filtering
- direction: Data direction filter - limit: Maximum number of records to return - projectId: Project identifier for scoped data access - apiKey: Additional API key for backend data source

Transfer Types¶

HTTP Pull¶

Consumer pulls data through the Data Plane using HttpData-PULL transfer type:

sequenceDiagram
    Consumer->>+Consumer Data Plane: Request data
    Consumer Data Plane->>+Provider Data Plane: GET /public/v2/data
    Provider Data Plane->>+Source: Fetch data
    Source-->>-Provider Data Plane: Data
    Provider Data Plane-->>-Consumer Data Plane: Data
    Consumer Data Plane-->>-Consumer: Data

HTTP Push¶

Provider pushes data to consumer endpoint:

sequenceDiagram
    Provider Data Plane->>+Source: Fetch data
    Source-->>-Provider Data Plane: Data
    Provider Data Plane->>+Consumer Data Plane: POST data
    Consumer Data Plane-->>-Provider Data Plane: ACK

Authentication¶

Contract-Based Authentication¶

Data transfers use contract agreement IDs for authentication:

Contract-Id: {{contractAgreementId}}
Authorization: {{contractAgreementId}}

Headers: - Contract-Id: Contract agreement identifier from negotiation - Authorization: Same contract agreement ID used for authorization

Authentication Flow¶

Complete contract negotiation to obtain contractAgreementId
Initiate transfer process with HttpData-PULL type
Use contract agreement ID in both Contract-Id and Authorization headers
Include API management key for gateway access

Environment Variables Used¶

The following variables are commonly used in data plane requests:

{{protocol}}: HTTP or HTTPS
{{apiGatewayHost}}: API Gateway hostname
{{consumerId}}: Consumer participant identifier
{{contractAgreementId}}: Contract agreement identifier from negotiation

Error Handling¶

Transfer Errors¶

{
  "@type": "DataFlowError",
  "errorCode": "TRANSFER_FAILED",
  "message": "Failed to connect to source",
  "processId": "transfer-1"
}

Common Error Codes¶

Code	Description
`401 Unauthorized`	Invalid contract ID or API key
`403 Forbidden`	Contract agreement not valid or expired
`404 Not Found`	Data source not available
`500 Internal Server Error`	Backend data source error
`502 Bad Gateway`	Provider backend unavailable
`504 Gateway Timeout`	Request timeout to provider