Universal API

Die Universal API ist eine Abstraktionsschicht über verschiedene Speicher-Backends, auch Persistenzen genannt. Diese Abstraktion unterstützt juristische 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 Tenant kann jeder Persistenztyp nur einmal verwendet werden.

Eine Tenant-weite Standardeinstellung legt fest, welche Persistenz genutzt wird. Anwendungen können pro Anfrage explizit auf unterschiedliche Persistenzen zugreifen.

Nicht alle Persistenzen unterstützen die gleichen Funktionen. Die folgende Tabelle zeigt, welche Fähigkeiten die einzelnen Persistenzen bieten.

Die Universal API stellt Dokumentenfunktionen über alle unterstützten Archive bzw. Persistenzen hinweg bereit. Nicht alle Persistenzen sind gleich – es gibt sowohl schematische als auch verhaltensbezogene Unterschiede. Manche sind geringfügig (z. B. unterschiedliche Länge der Versionsnummern), andere gravierend (z. B. Kategorien haben keine ID, sondern nur einen Namen). Die Universal API verfolgt das Ziel, trotz dieser Unterschiede eine harmonisierte Fassade für alle unterstützten Persistenzen zu bieten.

Wir streben an, den größtmöglichen gemeinsamen Nenner zu unterstützen, wo dies sinnvoll ist. Wir lassen uns nicht von Ausreißern im Funktionsumfang einzelner Persistenzen 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 dort, wo dies nicht möglich ist, Ausnahmen werfen. Wir akzeptieren, dass sich Persistenzen zur Laufzeit unterschiedlich verhalten können.

Das erleichtert es,

• einen Standard für Dokumentenfunktionen zu etablieren, da wir uns nicht am schwächsten Glied orientieren müssen,
• Best Practices zu nutzen, da diese der Mehrheit der Persistenzen zugutekommen.

Es wird jedoch schwieriger,

• das Laufzeitverhalten vorherzusagen, da sich die API je nach gewählter Persistenz unterschiedlich verhalten kann (dies könnte zukünftig durch eine Limitations-API abgemildert werden),
• universellen Code zu schreiben, da mehr Ausnahmebehandlungen implementiert werden müssen.

Kontexts

Kontexte bieten eine metadatenbasierte Gruppierung von Dokumenten. Dokumente können einem Kontext zugeordnet werden. Kontexte sind zum Beispiel Akte/Mandat, 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 bereitstellen, der mit einer “Akte” (stp.doc.matter) vergleichbar ist.

Versionen

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

Die neueste Version spiegelt den aktuellsten Stand wider.

Alle Versionen sind chronologisch geordnet.

Renditionen

Eine Rendition ist eine alternative Representation einer Dokumentenversion, zum Beispiel:

stp.doc.original – der Originalinhalt

stp.doc.preview – eine anzeigefertige Vorschau

Anwendungen können eigene Renditionen definieren. Diese können von allen Anwendungen gelesen, aber nur von der erstellenden Anwendung geschrieben und gelöscht werden.

Named Values

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

Ereignisse

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

APIs

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

• Upload API
• Download API
• Metadata API Für .NET stellen wir das NuGet-Paket STP.Documents.Client über unseren privaten Technology-Partner-NuGet-Feed bei STP.TechnologyPartner bereit. Weitere Informationen zur Arbeit mit dem NuGet-Registry finden Sie in der GitHub-Dokumentation.

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 Aktualisierungstoken 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. Geben Sie dabei bitte an, welche Art von Anwendung Sie entwickeln und wie diese die juristische Arbeit Ihrer Nutzer vereinfacht. Im Rahmen des Onboardings müssen Sie außerdem unsere Technologiepartnervereinbarung akzeptieren.

Anschließend erhalten Sie Zugang zu unserem privaten Technology Partner NuGet-Feed unter STP.TechnologyPartner, wo Sie alle unsere Pakete finden.

Bitte beachten Sie, dass Documents-Kunden zunächst freigeschaltet werden müssen 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 im Rahmen einer Kooperationsvereinbarung allen Documents-Kunden zur Verfügung stellen.