Dokumentacja API: Metadane i pochodzenie danych

Ta strona dokumentuje usługę Metadanych (openapi-metadata.yaml, port 8081) oraz usługę Pochodzenia danych (openapi-lineage.yaml, port 8084). Obie udostępniane są pod ścieżką /api/v1 i wymagają tokenu JWT bearerAuth. Operacje CRUD potoków również znajdują się w usłudze metadanych — zobacz stronę dokumentacji silnika potoków.

Połączenia

Połączenia rejestrują systemy zewnętrzne. Przechowywane poświadczenia są referencjami do skarbca (vault); API nigdy nie zwraca hasła w postaci jawnej.

listConnections przyjmuje workspaceId (zapytanie, uuid). Wyliczenie Connection.type: TERADATA, SNOWFLAKE, DATABRICKS, SAP_HANA, MSSQL, ORACLE, POSTGRESQL, MYSQL, KAFKA, GCS, AZURE_BLOB. testStatus: UNKNOWN | SUCCESS | FAILED. ConnectionCreate przyjmuje encryptedPassword (referencja do skarbca). Pola ConnectionTestResult: success, latencyMs, message, serverVersion, testedAt.

// POST /api/v1/connections  →  201 Created
// Request: ConnectionCreate
{
  "name": "teradata-prod",
  "type": "TERADATA",
  "host": "teradata.polkomtel.pl",
  "port": 1025,
  "database": "DWH",
  "username": "dataflow_svc",
  "encryptedPassword": "vault://connections/teradata-prod"
}

// POST /api/v1/connections/{id}/test  →  200 OK  (ConnectionTestResult)
{
  "success": true,
  "latencyMs": 42,
  "message": "Connection established",
  "serverVersion": "Teradata 17.20",
  "testedAt": "2025-12-15T14:30:00Z"
}

Jakość

Reguły jakości definiują kontrole jakości danych dla potoku; wyniki rejestrują każde wykonanie kontroli.

listQualityRules przyjmuje pipelineId (zapytanie, uuid). listQualityResults przyjmuje pipelineId, ruleId (uuid) oraz limit (domyślnie 50). Wyliczenie QualityRule.type: ROW_COUNT, NOT_NULL, UNIQUE, REFERENTIAL, CUSTOM_SQL, FRESHNESS, SCHEMA_MATCH, VALUE_RANGE, REGEX_MATCH, ACCEPTED_VALUES. severity: WARNING | ERROR | CRITICAL. onFailure: FAIL | WARN | SKIP_TARGET | QUARANTINE.

// POST /api/v1/quality/rules  →  201 Created
// Request: QualityRuleCreate
{
  "pipelineId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "customer-id-not-null",
  "type": "NOT_NULL",
  "column": "CUSTOMER_ID",
  "severity": "ERROR",
  "onFailure": "QUARANTINE"
}

// GET /api/v1/quality/results?pipelineId=...&limit=50  →  200 OK
[
  {
    "id": "qr-0001",
    "ruleId": "rule-0001",
    "pipelineId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "passed": false,
    "failedRows": 17,
    "severity": "ERROR",
    "checkedAt": "2025-12-15T02:14:00Z"
  }
]

Katalog

Katalog danych umożliwia przeglądanie zbiorów danych wykrytych poprzez połączenia.

listCatalogDatasets przyjmuje search, connectionId (uuid) oraz tag. CatalogDataset.type: TABLE | VIEW | MATERIALIZED_VIEW | EXTERNAL. Każdy zbiór danych zawiera columns[] (CatalogColumn — name, dataType, nullable, isPrimaryKey, classification).

// PUT /api/v1/catalog/datasets/{id}/tags  →  200 OK
// Request: { "tags": ["billing", "pii", "gold"] }
{
  "id": "ds-0001",
  "name": "DWH.CUSTOMERS",
  "type": "TABLE",
  "tags": ["billing", "pii", "gold"],
  "columns": [
    { "name": "CUSTOMER_ID", "dataType": "BIGINT", "nullable": false, "isPrimaryKey": true, "classification": "INTERNAL" }
  ]
}

Nadzór

Nadzór zarządza klasyfikacjami danych oraz przeszukiwalnym dziennikiem audytu.

getAuditLog przyjmuje category, userId (uuid), from/to (date-time) oraz limit (domyślnie 100). DataClassification.level: PUBLIC | INTERNAL | CONFIDENTIAL | RESTRICTED. AuditLogEntry.category: PIPELINE | CONNECTION | USER | WORKSPACE | SECURITY | SYSTEM.

// POST /api/v1/governance/classifications  →  201 Created
// Request: DataClassificationCreate
{
  "name": "Subscriber PII",
  "level": "RESTRICTED",
  "description": "Personal data of Polkomtel subscribers"
}

RODO

Endpointy RODO obsługują żądania dostępu osoby, której dane dotyczą (DSAR, SLA 30 dni), rejestry zgód oraz mapowanie danych zgodnie z artykułem 30.

listDsars przyjmuje status, requestType, page (domyślnie 0), size (domyślnie 20). getDataMap przyjmuje workspaceId (uuid). DsarRequest.requestType: ACCESS | ERASURE | RECTIFICATION; status: SUBMITTED | IN_PROGRESS | COMPLETED | REJECTED. DataMapReport zawiera totalColumnsScanned, piiColumnsFound, rodoRelevantColumnsFound, entries[] oraz zestawienia klasyfikacji/wrażliwości.

// POST /api/v1/gdpr/dsar  →  201 Created
// Request: DsarSubmitRequest
{
  "subjectId": "5d6e7f80-1111-2222-3333-444455556666",
  "requestType": "ERASURE",
  "subjectEmail": "subscriber@example.pl",
  "details": "Right to be forgotten request"
}

// Response: DsarSubmitResponse
{
  "trackingId": "dsar-2025-001847",
  "status": "SUBMITTED",
  "slaDueAt": "2026-01-14T14:30:00Z"
}

// GET /api/v1/gdpr/data-map?workspaceId=...  →  200 OK  (DataMapReport)
{
  "totalColumnsScanned": 4821,
  "piiColumnsFound": 312,
  "rodoRelevantColumnsFound": 287,
  "entries": [
    { "dataset": "DWH.CUSTOMERS", "column": "PESEL", "classification": "RESTRICTED", "sensitivity": "HIGH" }
  ]
}

Administracja — Użytkownicy

listUsers przyjmuje workspace (uuid), role, search, active (bool), page (domyślnie 0), size (domyślnie 20). getUserActivity przyjmuje since (date-time). Wyliczenie role, używane wszędzie, to ADMIN | ENGINEER | ANALYST | VIEWER. createUser zwraca 409 przy zdublowanym użytkowniku.

// POST /api/v1/admin/users  →  201 Created
// Request: CreateUserRequest
{
  "email": "anna.kowalska@polkomtel.pl",
  "displayName": "Anna Kowalska",
  "role": "ENGINEER",
  "workspaceId": "9c1f0e2a-1111-2222-3333-444455556666"
}

// GET /api/v1/admin/users?page=0&size=20  →  200 OK  (UserListResponse)
{
  "items": [
    { "id": "u-1001", "email": "anna.kowalska@polkomtel.pl", "role": "ENGINEER", "active": true }
  ],
  "total": 134,
  "page": 0,
  "size": 20
}

Administracja — Obszary robocze

// POST /api/v1/admin/workspaces/{id}/members  →  201 Created
// Request: AddMemberRequest
{
  "userId": "u-1001",
  "role": "ANALYST"
}

Administracja — Dziennik audytu

queryAdminAuditLog przyjmuje userId, workspaceId (uuid), action, resourceType, since/until (date-time), page (0), size (20). getAdminAuditStats przyjmuje workspaceId (uuid) oraz days (domyślnie 30). exportAdminAuditLog przyjmuje te same filtry plus format (json | csv, domyślnie json) i zwraca treść w postaci ciągu znaków typu application/json lub text/csv.

// GET /api/v1/admin/audit?page=0&size=20  →  200 OK  (AuditLogResponse)
{
  "items": [
    { "action": "PIPELINE_UPDATE", "resourceType": "PIPELINE", "userId": "u-1001", "at": "2025-12-15T14:30:00Z" }
  ],
  "total": 982,
  "page": 0,
  "size": 20
}

Administracja — Ustawienia systemowe

// PUT /api/v1/admin/settings/{key}  →  200 OK
// Request: SetSettingRequest
{ "value": "30" }

Usługa Pochodzenia danych

Usługa Pochodzenia danych śledzi pochodzenie zbiorów danych i kolumn, analizę wpływu oraz przyjmuje zdarzenia OpenLineage. Identyfikatory zbiorów danych używają formatu namespace.name — na przykład teradata.DWH.CUSTOMERS.

Graf pochodzenia

getColumnLineage przyjmuje w pełni kwalifikowany identyfikator kolumny, taki jak ns.table.column.

// GET /api/v1/lineage/datasets/teradata.DWH.CUSTOMERS  →  200 OK  (LineageGraph)
{
  "datasetId": "teradata.DWH.CUSTOMERS",
  "upstream": ["teradata.STG.CUSTOMERS_RAW"],
  "downstream": ["snowflake.DWH.DIM_CUSTOMER"],
  "jobs": ["billing-daily-load"]
}

Przechodzenie

getUpstreamLineage i getDownstreamLineage przyjmują depth (domyślnie 5). getSubgraph przyjmuje depth (domyślnie 3) oraz direction (UPSTREAM | DOWNSTREAM | BOTH, domyślnie BOTH).

// GET /api/v1/lineage/upstream/snowflake.DWH.DIM_CUSTOMER?depth=3  →  200 OK
[
  { "datasetId": "teradata.DWH.CUSTOMERS", "depth": 1 },
  { "datasetId": "teradata.STG.CUSTOMERS_RAW", "depth": 2 }
]

Analityka

ImpactAnalysis.riskLevel: LOW | MEDIUM | HIGH | CRITICAL; impactedDatasets[].impactType: DIRECT | INDIRECT. Pola LineageStats: totalDatasets, totalEdges, totalJobs, totalColumnLinks, orphanDatasets, maxDepthUpstream, maxDepthDownstream, lineageBreaks.

// GET /api/v1/lineage/impact/teradata.DWH.CUSTOMERS  →  200 OK  (ImpactAnalysis)
{
  "datasetId": "teradata.DWH.CUSTOMERS",
  "riskLevel": "HIGH",
  "impactedDatasets": [
    { "datasetId": "snowflake.DWH.DIM_CUSTOMER", "impactType": "DIRECT" },
    { "datasetId": "snowflake.MART.CHURN_SCORE", "impactType": "INDIRECT" }
  ]
}

Wyszukiwanie

searchLineage wymaga q i przyjmuje type, connection oraz entity (DATASET | COLUMN, domyślnie DATASET); zwraca 400, gdy brakuje q. getHotDatasets przyjmuje limit (domyślnie 10).

// GET /api/v1/lineage/search?q=customer&entity=DATASET  →  200 OK
[
  { "datasetId": "teradata.DWH.CUSTOMERS", "name": "CUSTOMERS", "connection": "teradata-prod" }
]

Zdarzenia OpenLineage

getRecentEvents przyjmuje limit (domyślnie 100). RunEvent.eventType: START | RUNNING | COMPLETE | ABORT | FAIL | OTHER; zawiera run (RunFacet), job (JobFacet) oraz inputs[]/outputs[] (DatasetEvent z fasetami schematu, źródła danych i pochodzenia kolumn).

// POST /api/v1/lineage/events  →  201 Created
// Request: RunEvent (OpenLineage)
{
  "eventType": "COMPLETE",
  "eventTime": "2025-12-15T02:30:00Z",
  "run": { "runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" },
  "job": { "namespace": "dataflow", "name": "billing-daily-load" },
  "inputs": [{ "namespace": "teradata", "name": "DWH.CUSTOMERS" }],
  "outputs": [{ "namespace": "snowflake", "name": "DWH.DIM_CUSTOMER" }]
}

// Response
{ "status": "RECORDED", "job": "billing-daily-load" }

// POST /api/v1/lineage/events/batch  →  201 Created
{ "status": "ACCEPTED", "accepted": 48, "total": 50 }