Dokumentacja API: przegląd

Platforma DataFlow AI udostępnia mikroserwisowe API REST poprzedzone pojedynczą API Gateway. Każde żądanie klienta wchodzi przez bramę, która uwierzytelnia JWT, stosuje ograniczanie liczby żądań per-trasa, dołącza identyfikator korelacji i przezroczyście przekazuje wywołanie do usługi backendowej będącej właścicielem prefiksu trasy.

Bazowe adresy URL

Cały ruch klientów powinien być kierowany do bramy. Usługi backendowe są również osiągalne bezpośrednio w lokalnym developmencie na potrzeby debugowania.

Każda usługa backendowa publikuje także serwer produkcyjny https://api.dataflow.polkomtel.pl/api/v1 — czyli ścieżkę, do której docierasz przez bramę. Każdy funkcjonalny punkt końcowy ma prefiks /api/v1.

Usługi i porty

Platforma jest zbudowana z pięciu usług specyfikowanych w OpenAPI plus trzech usług dostępnych tylko przez proxy. Wszystkie specyfikacje deklarują openapi: 3.1.0 oraz info.version: 1.0.0.

Routing bramy

Brama mapuje każdy prefiks trasy na usługę backendową. Większość ścieżek bramy to ponowne eksporty specyfikacji backendowych zamontowane przez $ref; brama definiuje także sześć własnych operacji pierwszej klasy (health, copilot, migration, CDC).

Operacje należące do bramy

Te sześć operacji jest definiowanych bezpośrednio przez bramę, a nie ponownie eksportowanych ze specyfikacji backendowej.

// GET /health  →  200 OK
{
  "status": "UP",
  "gateway": "dataflow-api-gateway"
}

Wersjonowanie

Platforma używa wersjonowania opartego na ścieżce. Obecna i jedyna wersja to v1, osadzona w każdej funkcjonalnej trasie jako /api/v1/....

• Wszystkie pięć specyfikacji OpenAPI deklaruje info.version: 1.0.0.
• Punkt końcowy bramy GET /health jest bez wersji — nie nosi prefiksu /api/v1.
• Nowa wersja główna, jeśli zostałaby wprowadzona, pojawiłaby się jako nowy segment ścieżki (/api/v2/...); trasy v1 pozostają stabilne.

Uwierzytelnianie

Platforma uwierzytelnia za pomocą Keycloak OIDC + tokenów JWT Bearer.

• Schematy bezpieczeństwa. Brama deklaruje dwa schematy — oidcAuth (openIdConnect) oraz bearerAuth (http / bearer / JWT). Usługi backendowe deklarują tylko bearerAuth.
• Odkrywanie OIDC: https://auth.dataflow.polkomtel.pl/realms/dataflow/.well-known/openid-configuration
• Realm: dataflow
• Identyfikatory klientów: dataflow-ui (publiczny, Authorization Code + PKCE) oraz dataflow-api (poufny, Client Credentials).
• Nagłówek: Authorization: Bearer <token>

Wymagane claimy JWT

Każde uwierzytelnione żądanie musi nieść token z następującymi claimami.

GET /api/v1/pipelines HTTP/1.1
Host: api.dataflow.polkomtel.pl
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...

Wyjątki

• GET /health (brama) jest nieuwierzytelniony — jego security w OpenAPI to [].
• Punkty końcowe webhooków (wyzwalacz orkiestratora, webhooki Git) uwierzytelniają się nagłówkami sygnatury HMAC — X-Webhook-Signature, X-Hub-Signature-256, X-Gitlab-Token — zamiast JWT.

Format błędów

Każda usługa zwraca w przypadku niepowodzenia jednolite ciało ErrorResponse.

{
  "error": "NOT_FOUND",
  "message": "Pipeline not found: f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": "2025-12-15T14:30:00Z"
}

Kody statusu HTTP

Błędy specyficzne dla bramy

Brama rozszerza ErrorResponse o własne tryby niepowodzeń.

// 429 Too Many Requests
{
  "error": "RATE_LIMITED",
  "message": "Rate limit exceeded for /api/v1/pipelines",
  "retryAfter": 42,
  "timestamp": "2025-12-15T14:30:00Z"
}

Ograniczanie liczby żądań i nagłówki korelacji

Brama stosuje te nagłówki do każdej przekazywanej odpowiedzi.

Limity liczby żądań są egzekwowane per trasa. Gdy okno zostanie wyczerpane, brama odpowiada 429 z wartością retryAfter (w sekundach). Zawsze rejestruj X-Request-Id po stronie klienta — to jedyny klucz korelacji do wsparcia i śledzenia we wszystkich usługach.

Paginacja

Nie istnieje ogólnoplatformowy kontrakt paginacji. We wszystkich usługach stosowane są trzy odrębne wzorce; nigdzie nie ma paginacji opartej na kursorze.

1. Paginacja offsetowa page/size

Używana przez Admin (/admin/users, /admin/audit) oraz listę DSAR GDPR. Parametry zapytania page (domyślnie 0) i size (domyślnie 20). Odpowiedź opakowuje elementy w total, page oraz size.

// GET /api/v1/admin/users?page=0&size=20  →  200 OK
{
  "items": [ /* UserResponse[] */ ],
  "total": 134,
  "page": 0,
  "size": 20
}

2. Listy ograniczone przez limit

Większość punktów końcowych „list / history / recent" akceptuje parametr zapytania limit (wartości domyślne się różnią — 10, 50, 100). Nie ma kursora; odpowiedź to czysta tablica.

GET /api/v1/quality/results?pipelineId=...&limit=50

3. Filtry okna czasowego

Punkty końcowe historii alertów i zdarzeń filtrują według czasu, a nie numeru strony, używając sinceSeconds, from oraz to.

GET /api/v1/monitor/alerts/history?sinceSeconds=86400

Indeks grup punktów końcowych

Pełne API jest udokumentowane na trzech stronach dokumentacji. Skorzystaj z tego indeksu, aby znaleźć właściwą grupę.

Liczby punktów końcowych

Usługi dostępne tylko przez proxy (copilot, migracja, CDC, connector-sdk) są udostępniane przez bramę, ale nie są formalnie specyfikowane poza sześcioma operacjami stub bramy.