Model podstawowy

API platformy DUST modeluje procesy związane z obiektami fizycznymi za pomocą niewielkiego zestawu zasobów, które można ze sobą łączyć. Rekord to cyfrowy zapis fizycznego przedmiotu; wszystko inne — identyfikatory, pliki, foldery, złożenia, udostępnianie, przesyłki — jest do rekordów dołączane, porządkuje je lub je przemieszcza. Ta strona jest mapą: każdemu pojęciu odpowiada jedna krótka sekcja z kluczowymi punktami końcowymi i linkiem do szczegółowego przewodnika.

Mapa nazw

Niektóre przestrzenie nazw API powstały przed obecnym słownictwem produktu. Aplikacja internetowa DICE i ta dokumentacja używają nazw z lewej kolumny; ścieżki API zachowują nazwy z prawej.

Nazwa w DICE / w dokumentacji	Przestrzeń nazw API	Uwagi
Rekordy	/api/v1/threads	—
Identyfikatory	/api/v1/tags	Starsze nazewnictwo tags w ścieżkach
Pliki	/api/v1/files	W niektórych schematach nazywane zasobami (resources)
Foldery i kategorie	/api/v1/bundles	Bundle to nazwa implementacyjna
Złożenia	/api/v1/assemblies	Złożenia to rekordy rodzaju assembly
Zespoły	/api/v1/teams	Wybierane dla każdego żądania za pomocą nagłówka Dust-Ctx-Team-Id (starszy nagłówek Dust-Ctx-Grp-Id jest nadal akceptowany)
Połączenia	/api/v1/connections	Schematy przesyłanych danych zachowują starsze nazewnictwo team link
Udostępnianie	/api/v1/sharing	—
Przesyłki	/api/v1/transfers	Starsze nazewnictwo transfers w ścieżkach
Wydzielenia	/api/v1/slices	—
Fabric	/api/v1/fabric	Graf pochodzenia obejmujący wiele organizacji
Certyfikaty	/api/v1/certificates, /api/v1/certificate-forms	—
Strony publiczne	/api/v1/public-pages, /api/v1/public-page-designs	Publikowanie wymaga uprawnienia zespołu publisher
Zdarzenia	/api/v1/events	—

Każde żądanie zawiera token Bearer wydany przez AuthD; punkty końcowe działające w zakresie organizacji — czyli prawie wszystkie — wymagają dodatkowo nagłówka Dust-Ctx-Org-Id (i opcjonalnie Dust-Ctx-Team-Id, aby wybrać zespół). Zobacz Uwierzytelnianie i Konwencje. Pełna dokumentacja na poziomie parametrów znajduje się w dokumentacji API.

Rekordy

Rekord to zapis jednego fizycznego składnika majątku, części, dokumentu lub elementu przepływu pracy: nazwa i opis, typowane dane pól, załączone pliki, powiązane identyfikatory oraz historia zdarzeń. Rekordy mają właściwość kind — zwykłe jednostki lub assembly (zobacz poniżej).

• POST /api/v1/threads — utworzenie jednego lub wielu rekordów
• GET /api/v1/threads — wyszukiwanie i wyświetlanie listy (paginacja kursorowa)
• GET /api/v1/threads/{thread_id} — pobranie jednego rekordu wraz z danymi pól
• POST /api/v1/threads/{thread_id}/data — wstawienie, aktualizacja lub usunięcie wartości pól
• PATCH /api/v1/threads/archive / PATCH /api/v1/threads/restore — cykl życia archiwizacji

Szczegóły: Przewodnik po API rekordów.

Pola i szablony

Wartości pól są typowane (text, number, date, select, odwołania do zasobów, a nawet pola, których wartościami są rekordy) i zagnieżdżone według typu. Szablony określają oczekiwane pola dla powtarzalnego rodzaju rekordu.

• POST /api/v1/templates / GET /api/v1/templates — tworzenie szablonów i wyświetlanie ich listy
• GET /api/v1/templates/{templateId} / PATCH /api/v1/templates/{templateId} — odczyt i aktualizacja

Identyfikatory

Identyfikator wiąże fizyczne oznakowanie — DUST, kod QR, kod kreskowy, symbol Data Matrix lub chip NFC — z rekordem, dzięki czemu skan wykonany w terenie prowadzi do cyfrowego zapisu. Przestrzeń nazw API to /api/v1/tags (starsze nazewnictwo).

• POST /api/v1/tags/extract — przetworzenie ujęcia DUST na kanoniczny odcisk cyfrowy bez powiązania
• POST /api/v1/tags/bind — powiązanie identyfikatora z rekordem
• POST /api/v1/tags/identify — znalezienie rekordu pasującego do skanu
• POST /api/v1/tags/verify — potwierdzenie, że skan pasuje do identyfikatorów określonego rekordu
• POST /api/v1/tags/unbind — odłączenie identyfikatora

Szczegóły: Przewodnik po API identyfikatorów.

Pliki

Pliki (w niektórych schematach nazywane zasobami) są przechowywane w magazynie obiektów i załączane do rekordów bezpośrednio lub za pośrednictwem pól typu zasób. Duże pliki są przesyłane za pomocą wznawialnego protokołu tus; małe — za pomocą pojedynczego żądania POST typu multipart.

• POST /api/v1/files — proste przesyłanie multipart
• POST /api/v1/files/finalize — przekształcenie zakończonych przesyłań tus w zapisy zasobów
• GET /api/v1/files/{resource_id}/download — pobieranie
• POST /api/v1/files/urls — krótkotrwałe podpisane adresy URL
• GET /api/v1/files/search — wyszukiwanie w plikach

Szczegóły: Przewodnik po API plików.

Zespoły i organizacje

Tożsamość jest zarządzana w AuthD; API platformy przypisuje każde żądanie działające w zakresie organizacji do organizacji i zespołu za pomocą nagłówków kontekstu. Zespoły są właścicielami rekordów, a udostępnianie, połączenia i przesyłki działają między zespołami.

• GET /api/v1/me — bieżący użytkownik i dostępne organizacje
• GET /api/v1/teams — zespoły widoczne dla wywołującego
• POST /api/v1/org/teams / PATCH /api/v1/org/teams/{team_id} — zarządzanie zespołami (administratorzy organizacji)
• POST /api/v1/org/teams/members — zarządzanie członkostwem (administratorzy organizacji)

Szczegóły: Zespoły, udostępnianie i połączenia.

Foldery i kategorie

Foldery i kategorie porządkują rekordy. W API jedne i drugie są pakietami (bundles) — kind: "folder" oznacza wyłączną przynależność, a kind: "category" niewyłączne oznaczanie — i pakiety można zagnieżdżać, tworząc drzewa.

• POST /api/v1/bundles — utworzenie (z kind i opcjonalnym elementem nadrzędnym childOfId)
• GET /api/v1/bundles / GET /api/v1/bundles/children — wyświetlenie listy lub stopniowe przechodzenie drzewa
• POST /api/v1/bundles/{bundle_id}/add / PATCH /api/v1/bundles/{bundle_id}/move — umieszczanie rekordów
• PATCH /api/v1/bundles/parent — zmiana elementu nadrzędnego pakietu

Złożenia i części

Złożenie to rekord rodzaju assembly, którego części są innymi rekordami — to struktura zestawienia materiałów. Części można chronić przed wymontowaniem, a listy części są agregowane przechodnio.

• GET /api/v1/assemblies — lista rekordów złożeń
• POST /api/v1/assemblies/{assembly_id}/parts / DELETE /api/v1/assemblies/{assembly_id}/parts — dołączanie i wymontowywanie części
• GET /api/v1/assemblies/{assembly_id}/rolled-up-parts — przechodnia lista części
• PATCH /api/v1/assemblies/{assembly_id}/kind — przekształcenie rekordu między rodzajami unit i assembly
• POST /api/v1/imports/plan / POST /api/v1/imports/commit — próbne uruchomienie i zatwierdzenie importu całego pakietu złożenia

Linki i relacje rekordów

Rekordy mogą odwoływać się do siebie nawzajem za pomocą typowanych linków. Definicje relacji nazywają rodzaje relacji; linki rekordów są ich wystąpieniami.

• POST /api/v1/relations / GET /api/v1/relations — definiowanie rodzajów relacji i wyświetlanie ich listy
• POST /api/v1/links / GET /api/v1/links — tworzenie linków między rekordami i wyświetlanie ich listy
• GET /api/v1/threads/{thread_id}/links — linki z perspektywy jednego rekordu
• DELETE /api/v1/links/{link_id} — rozłączenie

Udostępnianie

Udostępnianie przyznaje innemu zespołowi dostęp viewer lub editor do rekordu lub pakietu. Uprawnienia są przechowywane jako krotki relacji; podsumowanie dostępu pokazuje wynik efektywny, w tym dostęp dziedziczony.

• POST /api/v1/sharing — udostępnianie rekordów lub pakietów zespołom
• GET /api/v1/sharing — lista uprawnień (direction=in|out)
• GET /api/v1/sharing/access-summary — efektywny dostęp do jednego obiektu
• GET /api/v1/sharing/partner-inventory — wszystko, co udostępniono jednemu zespołowi partnera

Szczegóły: Zespoły, udostępnianie i połączenia.

Połączenia

Połączenie (w API: team link) to stałe porozumienie między dwoma zespołami — często należącymi do różnych organizacji — które umożliwia udostępnianie i przesyłki w dozwolonym kierunku przepływu danych. Ma ono procedurę uzgadniania zaproszenie/akceptacja/potwierdzenie oraz cykl życia wstrzymania i wznowienia.

• POST /api/v1/connections — utworzenie (zaproszenie)
• PATCH /api/v1/connections/accept / confirm / reject / cancel — uzgadnianie
• PATCH /api/v1/connections/pause / resume — wstrzymanie i przywrócenie
• POST /api/v1/connections/amend/propose — zaproponowanie zmiany kierunku

Przesyłki

Przesyłka (w API: transfer) przekazuje własność rekordów z jednego zespołu do innego: przygotowujesz manifest w wersji szkicu i wysyłasz go, a odbiorca go przyjmuje, odrzuca lub prosi o zmiany.

• POST /api/v1/transfers — utworzenie szkicu
• POST /api/v1/transfers/{transfer_id}/items — dodanie pozycji manifestu
• POST /api/v1/transfers/{transfer_id}/send — wysłanie do zespołu odbierającego
• POST /api/v1/transfers/{transfer_id}/respond — przyjęcie / odrzucenie / prośba o zmiany
• GET /api/v1/transfers — widoki odebranych, wychodzących i wysłanych

Semantyka i cykl życia: Przesyłki; podsumowanie punktów końcowych w sekcji Zespoły, udostępnianie i połączenia.

Wydzielenia

Wydzielenie tworzy nowy rekord na podstawie istniejącego w obrębie tego samego zespołu — wybrane pola, pliki i identyfikatory są kopiowane lub łączone — zwykle w celu przygotowania podzbioru, który można udostępnić.

• POST /api/v1/slices — wydzielenie jednego rekordu
• POST /api/v1/slices/batch — utworzenie wielu rekordów naraz
• GET /api/v1/slices/{slice_id} — wydzielenie wraz z linkami Fabric

Fabric

Fabric to warstwa pochodzenia obejmująca wiele organizacji: gdy rekordy są przemieszczane lub ujawniane poza granice zespołu, Fabric zapisuje graf powiązanych rekordów i kontroluje, jakie dokładnie dane może zobaczyć każda strona dalej w łańcuchu (ujawnienie), wersja po wersji.

• GET /api/v1/fabric/threads/{thread_id}/graph — graf pochodzenia widoczny z perspektywy rekordu
• GET /api/v1/fabric/links/{link_id}/context — dane obecnie ujawnione w linku
• POST /api/v1/fabric/threads/{thread_id}/disclosure/revise / redact — zmiana zakresu ujawnienia
• POST /api/v1/fabric/threads/{thread_id}/disclosure/push — wypchnięcie ujawnienia dalej w łańcuchu
• GET /api/v1/fabric/notifications — powiadomienia o ujawnieniach dla właścicieli dalej w łańcuchu

Pojęcia: Fabric.

Certyfikaty

Certyfikaty przekształcają dane rekordu w wystawione dokumenty, które można zweryfikować. Formularze certyfikatów to układy; generowanie wiąże formularz z rekordem według nazw pól.

Formularz może zawierać wiele stref kodów QR Vlink. Generowanie certyfikatu przyjmuje jedną konfigurację Vlink na każdy identyfikator strefy i zwraca wszystkie wystawione powiązania strefy z Vlink.

• POST /api/v1/certificate-forms / GET /api/v1/certificate-forms — zarządzanie formularzami
• POST /api/v1/certificates/preflight — sprawdzenie, czy formularz daje się rozwiązać względem rekordu
• POST /api/v1/certificates/generate — wystawienie certyfikatu
• GET /api/v1/certificates — lista certyfikatów rekordu
• POST /api/v1/certificates/void — unieważnienie certyfikatu

Pojęcia: Certyfikaty.

Strony publiczne

Strona publiczna to dostępny bez uwierzytelniania widok rekordu w sieci — cyfrowy paszport produktu, do którego konsument trafia, skanując identyfikator. To, co pokazuje, zależy wyłącznie od wielokrotnego użytku projektu strony publicznej, którego właścicielem jest zespół, więc publikowanie nie wymaga podawania treści dla poszczególnych rekordów: publikacja rozwiązuje projekt względem rekordu. Adres URL strony jest rezerwowany i wiązany z rekordem, zanim cokolwiek zostanie opublikowane, dzięki czemu etykiety można wydrukować wcześniej.

Opublikowanie projektu zamraża niezmienną wersję projektu; każda strona przypina jedną wersję projektu oraz jedną migawkę danych (wartości rozwiązane dla danego rekordu). Publikacja zbiorcza ponownie publikuje każdą stronę w zakresie — folderze, kategorii, szablonie lub jawnym wyborze — za pomocą jednej wersji projektu, jako przebieg w tle z własnym śledzeniem postępu i niepowodzeń.

Zarezerwowanie adresu URL strony i powiązanie go z rekordem są dostępne na poziomie członka — rezerwacja adresu niczego nie publikuje, więc etykiety można wydrukować, zanim ktokolwiek zdecyduje o publikacji. Wszystko, co upublicznia dane — publikowanie strony, jej aktywowanie lub archiwizowanie, tworzenie projektu, publikowanie wersji projektu, wdrażanie i publikacje zbiorcze — wymaga uprawnienia zespołu publisher (wynika ono z roli administratora zespołu), podobnie jak kontrole wstępne i podglądy. Rozstrzygająca jest wartość x-required-role każdej operacji w dokumentacji API.

• POST /api/v1/public-pages / POST /api/v1/public-pages/{publicPageId}/bind — zarezerwowanie stałego adresu URL strony, a następnie powiązanie go z rekordem
• GET / PUT /api/v1/public-pages/thread/{threadId} — odczyt strony rekordu lub jej pobranie albo utworzenie
• GET /api/v1/public-pages/thread/{threadId}/activity — anonimowe wyświetlenia i skany weryfikacyjne opublikowanej strony
• POST /api/v1/public-pages/{publicPageId}/publish — opublikowanie migawki za pomocą najnowszej wersji projektu
• PATCH /api/v1/public-pages/{publicPageId} — aktywowanie lub zarchiwizowanie strony bez zmiany jej adresu URL
• GET /api/v1/public-pages/{publicPageId}/publications — historia publikacji
• POST /api/v1/public-pages/preflight / preflight/batch — sprawdzenie, czy projekt daje się rozwiązać względem jednego lub wielu rekordów
• POST /api/v1/public-page-designs / GET / PATCH /api/v1/public-page-designs/{designId} — tworzenie szkicu projektu
• POST /api/v1/public-page-designs/{designId}/versions — opublikowanie wersji projektu (GET zwraca ich listę)
• POST /api/v1/public-pages/designs/{designId}/roll-out — wdrożenie najnowszej wersji projektu na wszystkich jego stronach
• POST /api/v1/public-pages/waves — rozpoczęcie publikacji zbiorczej (GET zwraca jej zapis przebiegu, pozycje i listę)
• POST /api/v1/public-pages/waves/{waveId}/retry-failed / cancel — ponowienie nieudanych operacji lub zatrzymanie pozostałej pracy

Wdrażanie działa tylko w przód: wersja projektu nigdy nie jest przywracana, a anulowanie publikacji zbiorczej pozostawia już opublikowane strony w wersji, którą otrzymały.

Pojęcia: Strony publiczne.

Zdarzenia

Każda istotna zmiana — edycje pól, powiązania, udostępnienia, przesyłki — jest zapisywana jako zdarzenie. Zdarzenia tworzą ścieżkę audytu, wyświetlaną w DICE jako dziennik transakcji.

• GET /api/v1/events — lista zdarzeń z możliwością filtrowania według rekordu, zespołu, akcji i czasu oraz opcjonalnym grupowaniem aktywności (groupBy)
  • lineage=upstream (razem z threadId) zwraca również zdarzenia każdego wcześniejszego rekordu w rodowodzie Fabric danego rekordu — pełną historię odebranego rekordu — w granicach tego, co ujawniło każde źródło. Wiersze z wcześniejszych ogniw zawierają obiekt lineage (rekord źródłowy, zespół źródłowy, link, przeskok) i mogą być oznaczone jako redacted; późniejsza zmiana ujawnienia przez źródło pojawia się jako wiersz fabric.disclosure.revised tylko do odczytu. Bez tego parametru odpowiedź zawiera wyłącznie zdarzenia samego rekordu.
  • resourceId, tagId lub fieldId (pojedynczo, razem z threadId) zawężają historię do jednego pliku, identyfikatora lub pola; certyfikat jest wskazywany za pomocą jego pliku. W połączeniu z lineage=upstream uwzględniany jest rodowód samego elementu.
  • Bez threadId parametr scope określa, czyją aktywność obejmuje lista: team (wartość domyślna) to działania samego aktywnego zespołu; shared dodaje działania innych zespołów i organizacji na rekordach, które są obecnie udostępnione aktywnemu zespołowi lub przez niego; upstream to wcześniejsza historia każdego rekordu odebranego przez zespół (wiersze zawierają lineage.localThreadId, czyli własną kopię zespołu); all łączy je wszystkie pod jednym kursorem. Odczyty grupowane akceptują team, shared i all.
  • ipAddress, userAgent i geolocation są zwracane wyłącznie dla działań wykonanych przez członków aktywnej organizacji wywołującego; dla działań każdej innej organizacji mają wartość null.
  • Historia rekordu odebranego w przesyłce lub utworzonego przez wydzielenie zaczyna się od zdarzenia transfer.received / slice.derived, przypisanego osobie, która przyjęła przesyłkę lub wykonała wydzielenie; taki rekord nie ma własnych zdarzeń created.thread ani bind.
• GET /api/v1/summary — główne wskaźniki liczbowe
• GET /api/v1/notifications — powiadomienia wywołującego

Co dalej

Szybki start

Wykonaj pierwsze uwierzytelnione wywołanie, korzystając z przewodnika szybkiego startu.

Klient TypeScript

Zamiast surowego HTTP używaj typowanego klienta @dustid/apid-client.

Konwencje

Nagłówki, paginacja i błędy w sekcji Konwencje API.

Pełna dokumentacja

Każda ścieżka, każdy parametr i każdy schemat w dokumentacji API.

Wyciągi PDF

Wyciąg PDF na żądanie pobierzesz za pomocą GET /api/v1/receipts/{kind}/{id}, gdzie kind to file, thread lub shipment, a id to odpowiedni UUID. Użyj zwykłego uwierzytelniania oraz nagłówków kontekstu aktywnej organizacji i zespołu. Odpowiedź ma typ application/pdf, zawiera nazwę pliku załącznika i jest objęta prywatnym buforowaniem z dyrektywą no-store. Nagłówek Accept-Language wybiera język wyciągu.

Wyciągi dotyczące plików zawierają metadane, zapisaną sumę kontrolną SHA-256 (jeśli jest dostępna), informacje o powiązanym rekordzie oraz dozwolone wpisy dziennika transakcji. Wyciągi dotyczące rekordów zawierają pola, identyfikatory, pliki i sumy kontrolne, relacje, informacje o złożeniu i rodowodzie oraz dozwolone dzienniki. Wyciągi dotyczące przesyłek zaczynają się od informacji o przesyłce, jej bieżącego stanu i manifestu, a następnie zawierają widoczne szczegóły rekordów i dzienniki. W przypadku oczekujących przesyłek używane są oferowane migawki; w pozostałych stanach — zapisy, do których wywołujący ma obecnie dostęp.

W przypadku pliku widocznego dzięki ujawnieniu podaj linkId; w przypadku pliku oferowanego w oczekującej przesyłce podaj transferId. Tych opcjonalnych parametrów zapytania typu UUID nie można łączyć i dotyczą one wyłącznie wyciągów dotyczących plików. Obowiązują je te same ograniczenia dostępu i ujawniania co odpowiedni podgląd.

Wyciągi zawierają datę i godzinę wygenerowania oraz kod QR z linkiem do DICE. Są to niepodpisane migawki zapisów widocznych dla wywołującego, a nie podpisy cyfrowe. Generowanie jest operacją tylko do odczytu: nie jest zapisywany żaden załącznik z wyciągiem ani zdarzenie dziennika transakcji. Eksport, w którym dziennik zawiera ponad 10 000 widocznych zdarzeń, kończy się niepowodzeniem zamiast cichego obcięcia danych. Linki w wyciągu nadal wymagają dostępu do DICE.