Konwencje żądań: nagłówki kontekstu, błędy, lokalizacja

Każdy punkt końcowy /api/v1/* o zakresie organizacji korzysta z tego samego kontraktu żądań: tokenu Bearer, dwóch nagłówków kontekstu wybierających organizację i zespół, w których działasz, treści JSON (przesyłanie plików używa zamiast tego multipart lub tus), jednej struktury błędów i paginacji kursorowej w punktach końcowych zwracających listy. Ta strona opisuje ten kontrakt; strony poszczególnych domen zakładają jego znajomość.

Nagłówki kontekstu

Niemal wszystko w DUST API należy do organizacji, a w jej ramach do zespołu. Organizację i zespół, w których działa żądanie, wybierasz za pomocą dwóch nagłówków:

Nagłówek	Wymagany	Wartość
Dust-Ctx-Org-Id	Tak, w punktach końcowych o zakresie organizacji	UUID organizacji.
Dust-Ctx-Team-Id	Nie	UUID zespołu. W przypadku pominięcia domyślnie używany jest zespół główny organizacji.

curl -fsS "https://apid.dustid.io/api/v1/threads" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Dust-Ctx-Team-Id: $DUST_TEAM_ID"

Grp to starsza pisownia

Dust-Ctx-Grp-Id to starsza nazwa nagłówka Dust-Ctx-Team-Id, nadal akceptowana wszędzie tam, gdzie akceptowany jest nowy nagłówek (gdy wysłane są oba, pierwszeństwo ma Dust-Ctx-Team-Id). Kilka kodów błędów (GROUP_ID_REQUIRED) i nazw pól również pochodzi sprzed zmiany nazwy „group” na „team” — w protokole zawsze odczytuj Grp/group jako „zespół”.

Szczegóły istotne w praktyce:

• Wartości nagłówków muszą być identyfikatorami UUID; nieprawidłowa wartość jest odrzucana z kodem 400 INVALID_REQUEST, zanim punkt końcowy zostanie wykonany.
• Warianty z prefiksem X- (X-Dust-Ctx-Org-Id, X-Dust-Ctx-Team-Id oraz starsza para) są akceptowane jako aliasy.
• Punkty końcowe, które wymagają kontekstu, ale go nie otrzymują, kończą się błędem z kodem ORG_ID_REQUIRED lub TEAM_ID_REQUIRED.
• Kilka punktów końcowych ma zakres użytkownika i nie wymaga kontekstu — najczęściej używanym jest GET /api/v1/me.

Kontekst jest granicą autoryzacji

Autoryzacja jest oceniana dla twojego użytkownika działającego w zespole wskazanym w nagłówkach. To samo wywołanie z innym Dust-Ctx-Team-Id może zwrócić inne wyniki: to, co możesz wyświetlać, odczytywać i zapisywać, odpowiada temu, co widzi dany zespół — jego własnym danym oraz wszystkiemu, co mu udostępniono. Wysłanie kontekstu, do którego nie należysz, nie zwiększa żadnych uprawnień; żądania są sprawdzane względem twoich rzeczywistych członkostw. Operacje na plikach, folderach, relacjach, linkach rekordów, importach złożeń, formularzach certyfikatów, Fabric, wydzieleniach, listach połączonych zespołów, stronach publicznych, projektach stron publicznych, aktywności i katalogu użytkowników wymagają bieżącego członkostwa w wybranym zespole i weryfikują, czy należy on do wybranej organizacji — zarówno w przypadku osób, jak i kont usług. Historia rekordu wymaga ponadto uprawnienia do wyświetlenia tego rekordu; wybranie ID rekordu nie przyznaje dostępu. Tworzenie rekordów (w tym tworzenie zbiorcze) i szablonów również wymaga bieżącego członkostwa w wybranym zespole. Listy członkostw administratorów organizacji nie wykraczają poza wybraną organizację. Zobacz Zespoły i udostępnianie.

Lokalizacja

Opcjonalny nagłówek Dust-Ctx-Locale wybiera język tekstu generowanego przez serwer i przeznaczonego dla użytkownika — przede wszystkim ciągów message w błędach:

Dust-Ctx-Locale: zh-CN

Obsługiwane ustawienia regionalne to de, es, fr, it, ja, pl, pt, en (domyślne) i zh-CN. Gdy nagłówek nie jest obecny, serwer używa standardowego nagłówka Accept-Language, a następnie języka angielskiego. Kody błędów są stałymi identyfikatorami i nigdy nie są lokalizowane — rozgałęziaj logikę według code, a wyświetlaj message.

Błędy

Nieudane żądania zwracają treść JSON o jednej, spójnej strukturze:

{
  "code": "UNAUTHORIZED",
  "message": "You are not authorized to perform this action",
  "status": 401,
  "detail": { }
}

Pole	Typ	Znaczenie
code	string	Stały, czytelny maszynowo kod błędu. Na jego podstawie rozgałęziaj logikę.
message	string	Opis czytelny dla człowieka, zlokalizowany zgodnie z Dust-Ctx-Locale.
status	number	Odpowiada kodowi stanu HTTP.
detail	object (opcjonalne)	Dodatkowy kontekst błędu, np. szczegóły walidacji.

Kody, które napotkasz najwcześniej:

Kod	Typowy status	Kiedy
INVALID_REQUEST	400	Nieprawidłowa treść, zapytanie lub nagłówek (szczegóły walidacji w detail).
UNAUTHORIZED	401	Brakujący, wygasły lub nieprawidłowy token Bearer.
FORBIDDEN	403	Uwierzytelniono, ale ten kontekst zespołu nie zezwala na tę operację.
NOT_FOUND / NO_DATA_FOUND	404	W tym kontekście nie jest widoczny żaden taki obiekt.
ORG_ID_REQUIRED / TEAM_ID_REQUIRED	400	Brak nagłówka kontekstu w punkcie końcowym z zakresem.
THREAD_DATA_CONFLICT	409	Konflikt współbieżności optymistycznej: twój widok rekordu był nieaktualny.

Każda odpowiedź zawiera też nagłówek x-request-id. Zapisuj go w logach i podawaj podczas kontaktu z pomocą techniczną — pozwala on dokładnie zlokalizować twoje żądanie w śladach serwera.

Błędy i wyniki skanowania to pełna dokumentacja: każdy kod, który możesz napotkać, wraz ze statusem, kanoniczne tabele wyników identyfikacji i weryfikacji, wskazówki dotyczące ponawiania oraz sposób zachowania raportu skanu, gdy operacja się nie powiedzie.

Wynik negatywny to też odpowiedź

Punkty końcowe skanowania zgłaszają wyniki za pomocą kodów błędów. Identyfikacja, która nic nie znajduje, zwraca 404 IDENTIFIER_NOT_FOUND — to jest odpowiedź, a nie błąd transportu. Niekompletne wyszukiwanie zwraca 503 SCAN_SEARCH_INCOMPLETE, co oznacza coś jeszcze innego. Rozgałęziaj logikę według code; zobacz tabelę wyników identyfikacji.

Paginacja

Punkty końcowe zwracające listy (rekordy, foldery, pliki, zdarzenia, szablony, …) używają paginacji kursorowej:

• Żądanie: parametry zapytania pageSize (długość strony) i cursor (nieprzezroczysty ciąg z poprzedniej strony). pageSize musi być liczbą całkowitą od 1 do 1000; niektóre punkty końcowe narzucają mniejsze maksimum. Pomiń go, aby użyć wartości domyślnej punktu końcowego.
• Punkty końcowe używające pageIndex akceptują liczby całkowite od 0 do 1 000 000. Ujemne lub ułamkowe wartości paginacji są odrzucane.
• Odpowiedź: tablica elementów oraz opcjonalne ciągi kursorów next i prev. Brak next oznacza, że jesteś na ostatniej stronie.

# First page
curl -fsS "https://apid.dustid.io/api/v1/threads?pageSize=50" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID"

# Follow the cursor
curl -fsS "https://apid.dustid.io/api/v1/threads?pageSize=50&cursor=$NEXT" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID"

{
  "threads": [ ... ],
  "next": "eyJjcmVhdGVkQXQiOi...",
  "prev": "eyJjcmVhdGVkQXQiOi..."
}

Kursory są nieprzezroczyste — zapisuj je i odtwarzaj, ale nigdy ich nie analizuj. Punkty końcowe zwracające listy, które obsługują sortowanie, przyjmują order (asc/desc) oraz specyficzny dla punktu końcowego orderCol (dla rekordów: createdAt, updatedAt, name).

Poziomy autoryzacji

Każda operacja wymaga jednego z trzech poziomów uprawnień, a prefiks ścieżki wskazuje go, zanim przeczytasz choćby jeden schemat:

Prefiks	Kto może wywołać	Uwagi
/api/v1/org/*	Administratorzy organizacji — użytkownicy z rolą admin (lub owner) w organizacji wskazanej przez Dust-Ctx-Org-Id	Tworzenie zespołów, aktualizacje zespołów, członkostwa
/api/v1/connections/*	Administratorzy zespołu — administratorzy działającego zespołu wskazanego przez Dust-Ctx-Team-Id	Cykl życia połączeń i zmiany kierunku
wszystkie pozostałe	Członkowie kontekstu żądania, chyba że operacja stanowi inaczej	Standardowy zakres funkcji

Każda operacja ma też w specyfikacji OpenAPI rozszerzenie x-required-role (member, publisher, team-admin lub org-admin) — traktuj je jako wiążącą zasadę dla danej operacji; operacja bez tej adnotacji wymaga roli member. publisher to uprawnienie nadawane w ramach członkostwa w zespole, a nie osobny poziom: jest wymagane, aby dane zespołu stały się publicznie dostępne do odczytu, a administratorzy zespołu zawsze je mają. Wywołanie operacji powyżej twojego poziomu zwraca 403 FORBIDDEN niezależnie od ładunku.

Treści, ID i znaczniki czasu

• Żądania mają Content-Type: application/json, chyba że punkt końcowy wyraźnie przyjmuje dane formularza multipart (skany identyfikatorów w /api/v1/tags/*, przesyłanie plików).
• ID to ciągi UUID zgodne z RFC 4122 (threadId, eventId, ID organizacji i zespołów, …). Traktuj je jako nieprzezroczyste.
• Znaczniki czasu (createdAt, updatedAt, archivedAt, …) to ciągi znaczników czasu w UTC.
• Zapisy są odnotowywane jako zdarzenia: modyfikacja rekordu dopisuje zdarzenie do jego historii zamiast niejawnie nadpisywać dane — odczyty takie jak GET /api/v1/threads/{thread_id} zwracają { thread, events }.

Zobacz także

• Szybki start z API — te konwencje w jednym działającym przepływie.
• Błędy i wyniki skanowania — każdy kod, tabele wyników identyfikacji i weryfikacji oraz wskazówki dotyczące ponawiania.
• Uwierzytelnianie i klucze API — skąd pochodzi token Bearer.
• Model podstawowy — co oznaczają rekordy, zespoły i identyfikatory.
• Pełna dokumentacja API — parametry i schematy poszczególnych punktów końcowych, generowane na podstawie bieżącej specyfikacji.