Public API
Blueputto Public API do uwierzytelnionego dostępu CRUD do rekordów obszaru roboczego, z wersjonowanymi endpointami, kluczami API, paginacją, filtrami i akcjami workflow.
Grzegorz
Public API to uwierzytelniona warstwa integracji Blueputto. Udostępnia te same podstawowe rekordy, z którymi aplikacja pracuje na co dzień, co pozwala systemom zewnętrznym tworzyć, odczytywać, aktualizować i usuwać dane operacyjne bez wprowadzania drugiego modelu treści obok interfejsu użytkownika.
To API działa pod adresem /v1 i zostało zaprojektowane do współpracy z kluczami API Keys na poziomie organizacji. Dzięki temu zespoły korzystają z tej funkcji, gdy dane Blueputto muszą trafić do strony internetowej, automatyzacji, skryptu importu, wewnętrznego dashboardu lub innego systemu produktowego.
Jedno wersjonowane API dla głównych zasobów obszaru roboczego
Punkt wejścia pod /v1 zwraca zwięzły zestaw danych odkrywczych z wersją API, formatem uwierzytelniania, adresem URL dokumentu OpenAPI oraz listą aktualnie udostępnionych zasobów.
W obecnej implementacji publiczna warstwa obejmuje:
documents,
items,
collections,
folders,
categories,
statuses,
labels,
oraz document templates.
Większość tych zasobów obsługuje standardową ścieżkę operacyjną: list, get, create, update i delete. API udostępnia też akcje specyficzne dla workflow tam, gdzie są potrzebne w UI, takie jak:
restore i permanent delete dla documents i items,
duplicate dla documents,
reorder dla categories, statuses i labels,
oraz filtrowanie active-only dla document templates.
To właśnie sprawia, że Public API jest czymś więcej niż warstwą eksportu tylko do odczytu. Ściśle odwzorowuje rzeczywisty cykl życia rekordów, który jest już widoczny w samym Blueputto.
Uwierzytelnianie i struktura odpowiedzi pozostają przewidywalne
Public API przyjmuje poświadczenia organizacji w jednej z dwóch standardowych form:
x-api-key,
lub Authorization: Bearer <key>.
Daje to zespołom elastyczność przy podłączaniu Blueputto do różnych środowisk uruchomieniowych, bram i stylów SDK. Sam klucz jest tworzony wewnątrz aplikacji na stronie ustawień API Keys.
Struktura odpowiedzi jest również celowo spójna. Odpowiedzi dla pojedynczego zasobu są zwracane wewnątrz obiektu data. Endpointy list zwracają data razem z meta, które obejmuje szczegóły paginacji, takie jak page, limit, total items, total pages oraz stan next lub previous page.
W całym obecnym zestawie zasobów API udostępnia także praktyczne filtry odzwierciedlające rzeczywiste przepływy pracy w UI, w tym search, deletedOnly, folderId, withoutFolder i activeOnly.
Zbudowane wokół tych samych reguł operacyjnych co aplikacja
Przydatność Public API Blueputto nie polega tylko na tym, że rekordy są dostępne z zewnątrz. Chodzi o to, że warstwa integracji działa według tych samych zasad, które produkt już egzekwuje w UI.
Na przykład usuwanie documents i items jest modelowane jako przepływ najpierw do kosza, a nie natychmiastowe zniszczenie. Niektóre operacje na documents mogą zwrócić odpowiedź o stanie zablokowania, gdy rekord nie jest obecnie edytowalny. Ograniczanie liczby żądań jest egzekwowane dla każdego klucza API, a domyślny limit backendu jest obecnie ustawiony na 5 req/s na klucz.
Dzięki temu API pozostaje zgodne z rzeczywistym zachowaniem aplikacji. Integracje zewnętrzne pracują z faktycznym modelem zasobów Blueputto, a nie z uproszczonym kanałem pobocznym, który zachowuje się inaczej niż produkt.
