Przegląd REST API

Interfejs REST API systemu Profound CMS jest obsługiwany przez usługę Rust translation_manager. Udostępnia bezgłowe punkty końcowe do odczytu/strumieniowania używane przez renderer oraz punkty końcowe zapisu dla treści, tłumaczeń i importu CSV.

Wszystkie przykłady używają {CMS_API_URL} jako bazowego adresu URL hosta interfejsu API CMS (na przykład https://cms.dev.tryprofound.com). Brak globalnego prefiksu ścieżki — trasy są montowane w katalogu głównym, np. {CMS_API_URL}/routes.

Uwierzytelnianie

Interfejs API korzysta z dwóch oddzielnych schematów, w zależności od punktu końcowego.

Klucz API (bezgłowe odczyty + uzupełnianie wariantów)

Wyślij klucz w nagłówku x-api-key lub jako parametr zapytania api_key:

curl '{CMS_API_URL}/dataset/post?websiteId=<uuid>' \
  -H 'x-api-key: <your-api-key>'

Klucze są weryfikowane w WorkOS i krótko buforowane w pamięci. W przypadku punktów końcowych odczytu klucz API jest wymagany tylko wtedy, gdy serwer ustawi require_schema_api_key = true; w przeciwnym razie dozwolone są anonimowe odczyty. Uzupełnianie wariantu (PATCH /dataset/{schema_name}) zawsze wymaga ważnego klucza z uprawnieniem content_write.

Korzysta z uwierzytelniania kluczem API: /routes, /route, /blocks*, /components*, /dataset/*, /schemas/*, /content-changes.

Token Bearer JWT (WorkOS)

Punkty końcowe do zarządzania wymagają tokenu użytkownika WorkOS w formacie JWT:

curl '{CMS_API_URL}/usage?orgId=<uuid>' \
  -H 'Authorization: Bearer <workos-jwt>'

Korzysta z uwierzytelniania Bearer: /translation, /translations, /usage, /csv.

Ustalanie witryny (tenanta)

Punkty końcowe z kluczem API ustalają docelową witrynę w następującej kolejności:

1. Parametr zapytania ?websiteId=<uuid>
2. Nagłówek Host, dopasowany do skonfigurowanej domeny witryny
3. Wartość rezerwowa CMS_WEBSITE_ID (single-tenant / lokalne środowisko deweloperskie)

Jeśli żadna z opcji nie rozwiąże się do prawidłowego UUID, punkt końcowy zwraca 400.

Model błędów

Kontrola kondycji

GET {CMS_API_URL}/health zwraca { "status": "ok" } i nie wymaga uwierzytelniania — użyj go do sond gotowości.