Universelle API

Die Universal API ist eine Abstraktionsschicht über verschiedene Speicher-Backends, auch Persistenzen genannt. Diese Abstraktion unterstützt rechtliche und geschäftliche Prozesse mit Dokumentenfunktionen, unabhängig davon, wo oder wie das Dokument tatsächlich gespeichert ist.

Persistenzen

Eine Persistenz ist das Speicher-Backend für Dokumente. Sie ermöglicht speicherunabhängige Prozesse und Integrationen.

In einem Mandanten kann jeder Persistenztyp nur einmal verwendet werden.

Eine mandantenweite Standardeinstellung legt fest, welche Persistenz verwendet wird. Anwendungen können pro Anfrage explizit auf verschiedene Persistenzen zugreifen.

Nicht alle Persistenzen unterstützen die gleichen Funktionen. Die folgende Tabelle zeigt, welche Funktionen für jede Persistenz verfügbar sind. Falls eine Funktion noch nicht von der Universal API unterstützt wird, kann sie möglicherweise dennoch über die eigene API der Persistenz verfügbar sein.

Die Universal API stellt Dokumentenfunktionen über unterstützte Archive oder Persistenzen hinweg bereit. Nicht alle Persistenzen sind gleich. Es gibt schematische und verhaltensbezogene Unterschiede zwischen ihnen. Einige sind geringfügig (unterschiedliche Länge der Versionsnummern), andere sind gravierend (z. B. haben Kategorien keine ID, sondern nur einen Namen). Angesichts dieser Unterschiede bemüht sich die Universal API, eine harmonisierte Fassade für alle unterstützten Persistenzen zu bieten.

Wir streben an, den größtmöglichen gemeinsamen Nenner zu unterstützen, wo es sinnvoll ist. Wir lassen uns nicht von Ausreißern den Standard der Universal API diktieren. Wir akzeptieren, dass bestimmte Persistenzen nicht alle Funktionen vollständig unterstützen. Wir erwarten, dass die Adapter dieser Persistenzen Unterschiede bestmöglich ausgleichen und Ausnahmen werfen, wo dies nicht möglich ist. Wir akzeptieren, dass sich diese Persistenzen zur Laufzeit unterschiedlich verhalten.

Es wird einfacher,

• einen Standard für Dokumentenfunktionen zu etablieren, da wir nicht durch die schwächste unterstützte Persistenz eingeschränkt sind
• Best Practices zu nutzen, da sie der Mehrheit der Persistenzen zugutekommen.

Es wird schwieriger,

• das Laufzeitverhalten vorherzusagen, da sich die APIs je nach konfigurierte Persistenz unterschiedlich verhalten können (wir könnten dies zukünftig mit einer Limitations-API abmildern)
• universellen Code zu schreiben, da mehr Fehlerbehandlung implementiert werden muss.

Kontexte

Kontexte ermöglichen eine metadatenbasierte Gruppierung von Dokumenten. Dokumente können einem Kontext zugeordnet werden. Kontexte sind zum Beispiel Akte/Sache, Rechtskategorie oder Beteiligter.

Andere Anwendungen, die mit Dokumenten arbeiten, sind dafür verantwortlich, Kontextrepräsentationen ihrer Containerobjekte innerhalb von STP.Documents zu pflegen.

Die Verfügbarkeit von Kontexttypen wird durch die verwendete Persistenz bestimmt. Wir gehen davon aus, dass alle unterstützten Persistenzen mindestens einen Kontexttyp haben, der mit einer „Sache“ (stp.doc.matter) vergleichbar ist.

Versionen

Jedes Dokument führt eine Versionshistorie. Eine Version hält den Zustand des Dokumenteninhalts (einschließlich Renditions) zu einem bestimmten Zeitpunkt fest.

Die neueste Version spiegelt den aktuellsten Stand wider.

Alle Versionen sind chronologisch geordnet.

Renditions

Eine Rendition ist eine Darstellung einer Dokumentenversion, zum Beispiel:

stp.doc.original – der Originalinhalt

stp.doc.preview – eine anzeigefertige Vorschau

Anwendungen können eigene Renditions definieren. Sie können von allen Anwendungen gelesen, aber nur von der erstellenden Anwendung geschrieben oder gelöscht werden.

Benannte Werte

Benannte Werte fügen entweder dem gesamten Dokument oder einer bestimmten Version zusätzliche Metadaten hinzu. Diese Werte können als individuelle Anmerkungen, Flags oder Hilfsdaten verwendet werden.

Ereignisse

Änderungen in den Persistenzen können über Ereignisse beobachtet werden (z. B. Dokument hochgeladen, Version aktualisiert usw.). Andere STP-Anwendungen können diese Ereignisse abonnieren.

APIs

Die Universal API besteht aus mehreren APIs. Details zu deren Endpunkten finden Sie in diesen Open API Spezifikationen:

• Upload API
• Download API
• Metadata API

Darüber hinaus gibt es weitere APIs, die auf der Universal API aufsetzen und Funktionen für alle Persistenzen bereitstellen:

• Search API
• Recognize API

Für dotnet stellen wir außerdem das STP.Documents.Client Nuget-Paket über unseren privaten Technology Partner Nuget-Feed unter STP.TechnologyPartner bereit. Mehr Informationen zum Arbeiten mit dem NuGet-Registry.

Beispielcode finden Sie unter STP.Documents.Example.

Wie starte ich mit der Entwicklung?

Um auf die STP Cloud APIs zuzugreifen, müssen Sie Ihre Anwendung bei uns registrieren. Dadurch kann Ihre Anwendung Zugriffs- und Refresh-Tokens erhalten, um im Namen Ihrer Nutzer auf die STP Cloud APIs zuzugreifen.

Bitte kontaktieren Sie uns unter support@stp.one, um die Registrierung Ihrer Anwendung zu starten. Bitte geben Sie an, welche Art von Anwendung Sie entwickeln und wie diese die juristische Arbeit Ihrer Nutzer vereinfacht. Während des Onboarding-Prozesses müssen Sie außerdem unsere Technology Partner Vereinbarung akzeptieren.

Anschließend erhalten Sie Zugriff auf unseren privaten Technology Partner Nuget-Feed unter STP.TechnologyPartner, wo Sie alle unsere Pakete finden.

Bitte beachten Sie, dass Documents-Kunden zunächst aktiviert werden und eine zusätzliche Lizenz- und Nutzungsvereinbarung abschließen müssen, bevor sie die API mit Ihrem Produkt nutzen können. Alternativ können Sie sich als Marketplace Partner bewerben und Ihre Lösung allen Documents-Kunden im Rahmen einer Kooperationsvereinbarung zur Verfügung stellen.