Eine Integration, die heute gegen die Schnittstelle geschrieben wird, soll morgen noch laufen. Diese Seite beschreibt, worauf sich eine Partneranwendung verlassen kann und was sie im Gegenzug aushalten muss.
Die Hauptversion steht in der Adresse
https://<mandant>.stp-cloud.de/documents/dms-cloud-api/api/v1/dms/documents/container
^^
Hauptversion- Die Hauptversion steht in jeder Adresse. Sie ist der einzige Auslöser, der eine Anpassung auf Partnerseite erzwingt.
- Es gibt keine Nebenversion in der Adresse. Abwärtskompatible Erweiterungen erscheinen innerhalb derselben Hauptversion, ohne Zutun der Partneranwendung.
- Es gibt keine Aushandlung über Kopfzeilen. Die Adresse ist der Weg.
Was innerhalb einer Hauptversion passieren darf
Diese Änderungen kommen ohne Vorwarnung und ohne neue Hauptversion:
| Änderung | Warum sie verträglich ist |
|---|---|
| Ein neuer Endpunkt kommt hinzu | Wer ihn nicht aufruft, merkt nichts |
| Ein optionales Feld in einer Anfrage kommt hinzu | Bestehende Aufrufe lassen es weg, das bisherige Verhalten bleibt |
| Ein Feld in einer Antwort kommt hinzu | Setzt voraus, dass unbekannte Felder ignoriert werden |
| Ein optionaler Abfrageparameter kommt hinzu | Wie ein optionales Anfragefeld |
| Ein neuer Wert in einer Aufzählung erscheint | Setzt voraus, dass unbekannte Werte verkraftet werden |
| Ein neuer Fehlercode erscheint | Setzt voraus, dass unbekannte Codes verkraftet werden |
| Eine Prüfung wird gelockert | Wer bisher streng aufgerufen hat, funktioniert weiter |
| Eine optionale Antwortkopfzeile kommt hinzu | Wer sie nicht liest, merkt nichts |
Die drei Pflichten der Partneranwendung
Aus der Tabelle folgen drei Anforderungen an jede Integration. Sie sind keine Empfehlung, sondern Voraussetzung dafür, dass eine Integration Bestand hat:
- Unbekannte Felder in Antworten ignorieren – nicht abbrechen, nicht protokollieren als Fehler.
- Unbekannte Aufzählungswerte verkraften – ein sinnvoller Rückfallwert statt einer Ausnahme.
- Unbekannte Fehlercodes verkraften – über den HTTP-Status entscheiden, wie in Fehlercodes beschrieben.
Was eine neue Hauptversion erzwingt
| Änderung | Warum sie bricht |
|---|---|
| Ein Feld entfällt | Bestehende Auswertungen laufen ins Leere |
| Ein Feld wird umbenannt | Entspricht Entfernen und Hinzufügen |
| Der Datentyp eines Feldes ändert sich | Bestehende Auswertungen scheitern |
| Die Bedeutung eines Feldes ändert sich | Der schlimmste Fall – es bricht lautlos |
| Ein bisher optionales Feld wird zur Pflicht | Bestehende Anfragen fallen durch die Prüfung |
| Ein Aufzählungswert entfällt | Zustandsautomaten auf Partnerseite brechen |
| Ein Endpunkt entfällt | Unmittelbarer Bruch |
| Der Aufbau der Adresse ändert sich | Ressourcen sind nicht mehr auffindbar |
| Das Blätterverfahren ändert sich | Durchlaufen von Ergebnislisten bricht |
| Die Bedeutung eines bestehenden Fehlercodes ändert sich | Wiederholungslogik bricht lautlos |
Was beim Wechsel auf eine neue Hauptversion gilt
Erscheint eine neue Hauptversion, verschwindet die alte nicht von einem Tag auf den anderen – beide laufen eine Zeit lang nebeneinander, damit eine Umstellung geplant und nicht erzwungen wird.
Wie dieser Übergang im Einzelnen abläuft, legt STP zum jeweiligen Zeitpunkt fest und teilt es den betroffenen Partnern und Kanzleien mit. Diese Seite nennt bewusst keine Fristen, Termine oder Vorlaufzeiten: Sie wären zum Zeitpunkt des Lesens womöglich überholt, und was für Sie gilt, ergibt sich aus Ihrer vertraglichen Vereinbarung mit STP.
Verlassen können Sie sich auf zweierlei:
- Es gibt keine stille Abschaltung. Ein Wechsel wird angekündigt, bevor er wirksam wird.
- Eine abgekündigte Version soll auch technisch erkennbar sein. Vorgesehen sind entsprechende Hinweise in den Antwort-Kopfzeilen, sodass eine Integration das auswerten und die eigene Betriebsmannschaft warnen kann, ohne auf eine E-Mail angewiesen zu sein. Solange es nur eine Hauptversion gibt, ist das eine Absichtserklärung und noch nichts, worauf man eine Auswertung stützen könnte.
Abkündigung einzelner Felder
Manchmal soll ein Feld verschwinden, ohne dass gleich eine neue Hauptversion nötig wäre. Der Ablauf ist dann:
- Das ersetzende Feld kommt hinzu.
- Das alte Feld wird in der Schnittstellenbeschreibung als
deprecatedgekennzeichnet. - Beide werden weiterhin ausgeliefert.
- Entfernt wird das alte Feld erst mit der nächsten Hauptversion – nie innerhalb der laufenden.
Werden bei einer Anfrage beide Felder geschickt, gewinnt das neue.
Was mit bereits importierten Dokumenten passiert
Nichts. Ein Dokument, das über v1 in das
Dokumentenmanagement gelangt ist, bleibt unverändert gültig – es ist ein
gewöhnliches Objekt des Dokumentenmanagements und nicht an die Version
gebunden, über die es hochgeladen wurde. Eine Anwendung auf
v2 liest Dokumente, die über v1 importiert
wurden, ohne Sonderbehandlung.
Der Connector hat seinen eigenen Aktualisierungsrhythmus
Der Connector läuft auf einem Server der Kanzlei und wird nach deren Zeitplan aktualisiert. Das ist bewusst entkoppelt – eine neue Version der Schnittstelle zwingt die Kanzlei nicht zu einem sofortigen Update, und ein Update in der Kanzlei zwingt den Partner zu nichts.
Was eine Partneranwendung davon merkt:
-
Sie kann den Stand abfragen.
GET /v1/platform/connector/heartbeatmeldet, ob der Connector der Kanzlei verbunden ist, welche Version er hat und welche Fähigkeiten er angemeldet hat. Das eignet sich, um die eigene Oberfläche anzupassen – etwa einen Hinweis zu zeigen, solange der Connector nicht erreichbar ist. - Ein zu alter Connector wird an der Cloud abgewiesen. STP kann eine Mindestversion festlegen und einzelne Versionen sperren, etwa wenn eine davon einen schwerwiegenden Fehler hat. Ein Aufruf an eine gesperrte oder zu alte Installation scheitert dann mit einer klaren Begründung, statt unterwegs zu verunglücken. Der Heartbeat meldet diesen Zustand ebenfalls, sodass die Ursache erkennbar ist, bevor der erste Fachaufruf scheitert.
Die Fähigkeitsliste ist eine Auskunft, keine Sperre. Die Cloud lehnt einen Aufruf nicht deshalb ab, weil eine Fähigkeit in der Liste fehlt; die Prüfung an der Cloud betrachtet die Version. Wo eine Funktion beim Connector tatsächlich fehlt, meldet er das bei der Ausführung zurück.
Die Schnittstellenbeschreibung
Die maßgebliche technische Beschreibung ist die OpenAPI-Beschreibung der jeweiligen Hauptversion. Sie ist die Quelle für Feldnamen, Datentypen und Pflichtangaben; diese Dokumentation erklärt die Zusammenhänge, ersetzt sie aber nicht.
Die jeweils gültige Fassung erhalten Sie über das STP Downloadportal – auf demselben Weg wie die Installationspakete. Sie eignet sich als Eingabe für einen Codegenerator und ist damit der schnellste Weg zu einem typisierten Client.