Änderungen von Dokument Schnittstellen

Zuletzt geändert von MACH ProForms GmbH am 07.08.2025

Von 98.2 nach 98.1 Von 102.1 nach 101.4

Von Version 101.4

bearbeitet von MACH ProForms GmbH
am 07.08.2025

Änderungskommentar: Es gibt keinen Kommentar für diese Version

Auf Version 98.2

bearbeitet von MACH ProForms GmbH
am 10.12.2024

Änderungskommentar: Es gibt keinen Kommentar für diese Version

Rohform
Im Layout

Zusammenfassung

Seiteneigenschaften (2 geändert, 0 hinzugefügt, 0 gelöscht)

Details

Seiteneigenschaften

Syntax

@@ -1,1 +1,1 @@
--XWiki 2.1
++Markdown 1.2

Inhalt

@@ -1,116 +1,46 @@
--(% class="wikigeneratedid" id="HAPISchnittstellen" %)
--MACH formsolutions stellt Schnittstellen zur Verfügung, um verschiedene Informationen über den Formularserver auszulesen, sowie Datensätze automatisiert abzurufen und zu aktualisieren.
++Die MACH ProForms GmbH setzt bei der Produktstrategie auf den API-First Ansatz. D.h., dass perspektivisch alle Funktionen über eine API erreichbar und ansteuerbar sind.
--(% class="wikigeneratedid" %)
--Die Schnittstellen beruhen auf dem REST-Standard. Sie werden über eine URL angesprochen. Hierbei gibt es einen festen Basispfad und einen ergänzenden Endpunkt. Der Basispfad ist bei jedem Aufruf gleich, die Endpunkte unterscheiden sich je nach Funktion. Ein Endpunkt spricht eine Funktionalität der Schnittstelle an.
++![[Schnittstellen|@Schnittstellen.jpg]]
--Um die API-Schnittstellen verwenden zu können, ist die Authentifizierung auf Mandantenbasis durch einen API-Key/Schlüssel erforderlich. Der API-Key kann beim Support Ihres Formularserverbetreibers beantragt werden.
--Die Anleitung für Formularserverbetreiber finden Sie in der [[Dokumentation zum Anlegen von API-Keys>>Main.02_FSSchnittstellen.09_API-Key]].
++# Übersicht der APIs
--(% class="box infomessage" %)
--(((
--Der Supermandant hat als übergeordnete Instanz Zugriff auf alle Mandanten.
--)))
++## Aktuelle APIs
--{{toc/}}
++* Die Dokumentation zum Anlegen von „[[API-Keys|Main.02_FSSchnittstellen.09_API-Key]]“ für Nutzung der Schnittstellen
++* Die Dokumentation der „[[Server-Information-API|Main.02_FSSchnittstellen.10_ServerInformationAPI]]“
++* Die Dokumentation der „[[Search-API|Main.02_FSSchnittstellen.03_SearchAPI]]“
++* Die Dokumentation der „[[Release-API|Main.02_FSSchnittstellen.02_ReleaseAPI]]“
++* Die Dokumentation der „[[Submission-API|Main.02_FSSchnittstellen.01_SubmissionAPI]]“
++* Die Dokumentation der „[[Error-API|Main.02_FSSchnittstellen.04_ErrorAPI]]“
--= Übersicht der APIs =
++## Veraltete APIs
--== Server-Information-API ==
++* Die Dokumentation der „[[Search-API-Metaform|Main.02_FSSchnittstellen.06_SearchAPIMetaform]]“
++* Die Dokumentation der „[[Massenverarbeitung von Formular-Eingängen-API|Main.02_FSSchnittstellen.08_MassenverarbeitungAPI]]“
++* Die Dokumentation der „[[CMS-Schnittstelle|Main.02_FSSchnittstellen.05_CMSSchnittstelle]]“
++* Die Dokumentation der „[[PDF Structure-API|Main.02_FSSchnittstellen.07_PDFStructureAPI]]“
--|(% style="width:250px" %)Zweck|allgemeine Informationen über den Server und die verfügbaren Schnittstellen
--|Ausgabeformat|JSON
--|weitere Informationen|
--|Dokumentation|[[Dokumentation Server-Information-API>>Main.02_FSSchnittstellen.10_ServerInformationAPI]]
++# Versionierung
--== Search-API ==
++Grundsätzlich legen wir unsere APIs für eine möglichst lange Betriebsphase aus und streben Versionskompatibilität an. Im Nachfolgenden finden Sie unsere Vorgehensweise im Detail.
--|(% style="width:250px" %)Zweck|Suchergebnisse, wie sie über die Benutzeroberfläche zu erlangen sind
--|Ausgabeformat|JSON
--|weitere Informationen|(((
--OpenAPI Spezifikation v3
++Wir behalten (soweit technisch möglich) immer zwei Versionen online. Sobald eine neue Version hinzukommt, wird die älteste Version mit einem zeitlichen Horizont von mindestens 6 Monaten abgekündigt. Nach dieser Frist ist die Version und alle ihre Minor-Versionen nicht mehr erreichbar.
--Damit die Suchlogik abgebildet und die Suchergebnisse gefiltert werden können, bietet die Schnittstelle einige Query-Parameter an, die an die URL angefügt werden können.
--)))
--|Dokumentation|[[Dokumentation Search-API>>path:/wiki/admindoku/view/Main/02_FSSchnittstellen/03_SearchAPI/]]
++Eine neue **Major-Version (1.x)** kann Änderungen beinhalten, welche nicht mehr abwärtskompatibel sein müssen (Abhängig von Ihrer Implementierung). Dies sind z.B.:
--== Release-API ==
--
--|(% style="width:250px" %)Zweck|Veröffentlichungen auslesen; sowohl Assistenten als auch PDF-Formulare
--|Ausgabeformat|JSON; CSV
--|weitere Informationen|(((
--OpenAPI Spezifikation v3
--
--Wir stellen mehrere Versionen der Release-API zur Verfügung.
--)))
--|Dokumentation|[[Dokumentation Release-API>>doc:.02_ReleaseAPI.WebHome]]
--
--== (% style="color:inherit; font-family:inherit; font-size:max(20px, min(24px, 12.8889px + 0.925926vw))" %)Submission-API(%%) ==
--
--|(% style="width:250px" %)Zweck|Abruf von Informationen zu eingegangenen Formularen und von Formulardaten
--|Ausgabeformat|JSON
--|weitere Informationen|(((
--OpenAPI Spezifikation v3
--
--Einreichungen zu einem Formular/Artikelnummer für den Mandanten
--
--* Übersicht der Einreichungen (nur Metadaten)
--* Einschränkung der Suche
--** nach Bearbeitungsstatus (z.B. "NEW")
--** nach Einreichungszeitpunkt
--
--Spezifische Einreichungen
--
--* Abruf einer konkreten Einreichung
--** Metadaten
--** Inhalte
--* Änderung des Bearbeitungsstatus einer Einreichung
--
--Wir stellen mehrere Versionen der Submission-API zur Verfügung.
--)))
--|Versionshistorie|[[Submission-API Release-Notes>>doc:.01_SubmissionAPI.Release-Notes.WebHome]]
--|Dokumentation|[[Dokumentation Submission-API>>Main.02_FSSchnittstellen.01_SubmissionAPI]]
--
--== Error-API ==
--
--|(% style="width:250px" %)Zweck|Auflistung von Fehlern im Antragsprozess; alternativer Zugang zu Fehlerinformationen, ohne einen Formularserver-Administrator zu kontaktieren
--|Ausgabeformat|JSON
--|weitere Informationen|(((
--
--
--Während des Antragsprozesses kann der Assistent unerwartet auf einen Fehler laufen.
--
--Mit der Error-API stellt MACH formsolutions eine Lösung bereit, Fehlerursachen festzustellen, ohne einen Formularserver-Administrator zu kontaktieren.
--
--Um die Schnittstelle verwenden zu können, ist es notwendig beim Assistentenstart eine "errorUrl" zu übergeben, wie unter [[Rücksprung-URLs>>https://wiki.machproforms.de/wiki/admindoku/view/Main/03_Steuerungsprozess/03_Portalintegration/]] beschrieben.
--In Fehlerfällen während des Antragsprozesses wird dadurch der Parameter "errorId" an die URL angehängt. Mit dieser ID können Informationen zum Fehler über die Schnittstelle ausgelesen werden.
--)))
--|Dokumentation|[[Dokumentation Error-API>>Main.02_FSSchnittstellen.04_ErrorAPI]]
--
--= Unterstützung von Vorgängerversionen und abgekündigten APIs =
--
--* Die Dokumentation der „[[Search-API-Metaform>>Main.02_FSSchnittstellen.06_SearchAPIMetaform]]“
--* Die Dokumentation der „[[Massenverarbeitung von Formular-Eingängen-API>>Main.02_FSSchnittstellen.08_MassenverarbeitungAPI]]“
--* Die Dokumentation der „[[CMS-Schnittstelle>>Main.02_FSSchnittstellen.05_CMSSchnittstelle]]“
--* Die Dokumentation der „[[PDF Structure-API>>Main.02_FSSchnittstellen.07_PDFStructureAPI]]“
--
--= Versionierung =
--
--Unsere APIs sind für eine lange Betriebsphase und Versionskompatibilität konzipiert.
--
--Wir behalten immer zwei Versionen online, soweit technisch möglich. Sobald eine neue Version hinzukommt, wird die älteste Version mit einem zeitlichen Horizont von mindestens 6 Monaten abgekündigt. Nach dieser Frist sind die veraltete Version und alle ihre Minor-Versionen nicht mehr erreichbar.
--
--Eine neue **Major-Version (1.x)** kann Änderungen beinhalten, die nicht abwärtskompatibel sind. Dies sind z.B.:
--
  * Authentifizierungsmethoden
  * Umbenennung und Löschung von Endpunkten
  * Löschung von HTTP-Methoden an vorhandenen Endpunkten
  * Umbenennung und Löschung von Parametern
--* Restrukturierung des Response-Objekts
++* Restrukturierung des Response-Objekt
--Eine neue **Minor-Version (x.1)** ist definitionsgemäß abwärtskompatibel zur **Major-Version**. Änderungen wären z.B.:
++Eine neue **Minor-Version (x.1)** ist per Definition abwärtskompatibel zur **Major-Version**. Dabei können sich aber folgende Dinge ändern:
  * Zusätzliche Endpunkte
  * Zusätzliche HTTP-Methoden an Endpunkten
  * Weitere (optionale) Parameter für eine Abfrage (z.B. Filterfunktion)
  * Erweitertes Response-Objekt
++
++# Versionshistorie
++
++Zu jeder API finden Sie als Unterknoten jeweils den "Release-Notes"-Artikel. Beispiel [[Submission-API|doc:.01_SubmissionAPI.Release-Notes.WebHome]].