Öffentliche API
Blueputto Öffentliche API für authentifizierten CRUD-Zugriff auf Workspace-Datensätze mit versionierten Endpunkten, API-Schlüsseln, Paginierung, Filtern und Workflow-Aktionen.
Grzegorz
Die Public API ist Blueputtos authentifizierte Integrationsschicht. Sie stellt dieselben zentralen Datensätze bereit, mit denen die Anwendung täglich arbeitet, sodass externe Systeme operative Daten erstellen, lesen, aktualisieren und löschen können, ohne neben der UI ein zweites Inhaltsmodell einzuführen.
Diese API ist unter /v1 verfügbar und für die Verwendung mit organisationsweiten API Keys konzipiert. Damit nutzen Teams sie immer dann, wenn Blueputto-Daten in eine Website, eine Automatisierung, ein Importskript, ein internes Dashboard oder ein anderes Produktsystem übertragen werden müssen.
Eine versionierte API für die wichtigsten Workspace-Ressourcen
Der Einstiegspunkt unter /v1 gibt eine kompakte Discovery-Payload mit der API-Version, dem Authentifizierungsformat, der URL des OpenAPI-Dokuments und der Liste der aktuell bereitgestellten Ressourcen zurück.
In der aktuellen Implementierung umfasst die öffentliche Oberfläche:
documents,
items,
collections,
folders,
categories,
statuses,
labels,
und document templates.
Die meisten dieser Ressourcen unterstützen den üblichen operativen Ablauf von Auflisten, Abrufen, Erstellen, Aktualisieren und Löschen. Die API stellt außerdem workflowspezifische Aktionen bereit, wo die UI sie benötigt, zum Beispiel:
Wiederherstellen und endgültiges Löschen für documents und items,
Duplizieren für documents,
Neuordnen für categories, statuses und labels,
sowie active-only-Filterung für document templates.
Genau das macht die Public API zu mehr als nur einer schreibgeschützten Exportschicht. Sie bildet den realen Lebenszyklus von Datensätzen eng nach, wie er bereits in Blueputto selbst sichtbar ist.
Authentifizierung und Antwortformat bleiben vorhersehbar
Die Public API akzeptiert die Organisations-Anmeldeinformationen in einer von zwei standardmäßigen Formen:
x-api-key,
oder Authorization: Bearer <key>.
Das gibt Teams Flexibilität, wenn sie Blueputto in verschiedene Laufzeitumgebungen, Gateways und SDK-Stile integrieren. Der Schlüssel selbst wird innerhalb der Anwendung auf der Einstellungsseite für API Keys erstellt.
Auch das Antwortformat ist bewusst konsistent. Antworten für einzelne Ressourcen werden in einer data-Hülle zurückgegeben. Listenendpunkte geben data zusammen mit meta zurück; darin enthalten sind Paginierungsdetails wie page, limit, Gesamtzahl der Einträge, Gesamtzahl der Seiten sowie der Status der nächsten oder vorherigen Seite.
Über den aktuellen Ressourcenumfang hinweg stellt die API außerdem praktische Filter bereit, die reale UI-Workflows widerspiegeln, darunter search, deletedOnly, folderId, withoutFolder und activeOnly.
Aufgebaut nach denselben operativen Regeln wie die App
Der nützliche Teil von Blueputtos Public API besteht nicht nur darin, dass Datensätze extern erreichbar sind. Er besteht darin, dass die Integrationsoberfläche denselben Regeln folgt, die das Produkt bereits in der UI durchsetzt.
Zum Beispiel ist das Löschen von documents und items als Papierkorb-zuerst-Ablauf modelliert und nicht als sofortige Zerstörung. Einige document-Operationen können eine Locked-State-Antwort zurückgeben, wenn der Datensatz derzeit nicht bearbeitbar ist. Rate Limiting wird pro API-Schlüssel durchgesetzt, wobei das standardmäßige Backend-Limit derzeit auf 5 req/s pro Schlüssel gesetzt ist.
Dadurch bleibt die API am tatsächlichen Verhalten der Anwendung ausgerichtet. Externe Integrationen arbeiten mit Blueputtos tatsächlichem Ressourcenmodell, nicht mit einem vereinfachten Nebenkanal, der sich anders verhält als das Produkt.
