Zum Inhalt springen

Änderungen von Dokument Schnittstellen

Zuletzt geändert von MACH ProForms GmbH am 07.08.2025
Von Version 96.1
bearbeitet von MACH ProForms GmbH
am 09.12.2024
Änderungskommentar: Es gibt keinen Kommentar für diese Version
Auf Version 102.1
bearbeitet von MACH ProForms GmbH
am 07.08.2025
Änderungskommentar: Es gibt keinen Kommentar für diese Version

Zusammenfassung

Details

Seiteneigenschaften
Syntax
... ... @@ -1,1 +1,1 @@
1 -Markdown 1.2
1 +XWiki 2.1
Inhalt
... ... @@ -1,44 +1,116 @@
1 -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.
1 +(% class="wikigeneratedid" id="HAPISchnittstellen" %)
2 +MACH formsolutions stellt Schnittstellen zur Verfügung, um verschiedene Informationen über den Formularserver auszulesen, sowie Datensätze automatisiert abzurufen und zu aktualisieren.
2 2  
3 -![[Schnittstellen|@Schnittstellen.jpg]]
4 +(% class="wikigeneratedid" %)
5 +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.
4 4  
5 -# Übersicht der API's
7 +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. 
8 +Die Anleitung für Formularserverbetreiber finden Sie in der [[Dokumentation zum Anlegen von API-Keys>>Main.02_FSSchnittstellen.09_API-Key]].
6 6  
7 -## Aktuelle API's
10 +(% class="box infomessage" %)
11 +(((
12 +Der Supermandant hat als übergeordnete Instanz Zugriff auf alle Mandanten.
13 +)))
8 8  
9 -* Die Dokumentation zum Anlegen von „[[API-Keys|Main.02_FSSchnittstellen.09_API-Key]]“ für Nutzung der Schnittstellen
10 -* Die Dokumentation der „[[Server-Information-API|Main.02_FSSchnittstellen.10_ServerInformationAPI]]“
11 -* Die Dokumentation der „[[Search-API|Main.02_FSSchnittstellen.03_SearchAPI]]“
12 -* Die Dokumentation der „[[Release-API|Main.02_FSSchnittstellen.02_ReleaseAPI]]“
13 -* Die Dokumentation der „[[Submission-API|Main.02_FSSchnittstellen.01_SubmissionAPI]]“
14 -* Die Dokumentation der „[[Error-API|Main.02_FSSchnittstellen.04_ErrorAPI]]“
15 +{{toc/}}
15 15  
16 -## Veraltete API's
17 += Übersicht der APIs =
17 17  
18 -* Die Dokumentation der „[[Search-API-Metaform|Main.02_FSSchnittstellen.06_SearchAPIMetaform]]“
19 -* Die Dokumentation der „[[Massenverarbeitung von Formular-Eingängen-API|Main.02_FSSchnittstellen.08_MassenverarbeitungAPI]]“
20 -* Die Dokumentation der „[[CMS-Schnittstelle|Main.02_FSSchnittstellen.05_CMSSchnittstelle]]“
21 -* Die Dokumentation der „[[PDF Structure-API|Main.02_FSSchnittstellen.07_PDFStructureAPI]]“
19 +== Server-Information-API ==
22 22  
23 -# Versionierung
21 +|(% style="width:250px" %)Zweck|allgemeine Informationen über den Server und die verfügbaren Schnittstellen
22 +|Ausgabeformat|JSON
23 +|weitere Informationen|
24 +|Dokumentation|[[Dokumentation Server-Information-API>>Main.02_FSSchnittstellen.10_ServerInformationAPI]]
24 24  
25 -Grundsätzlich legen wir unsere API's für eine möglichst lange Betriebsphase und somit für eine lange Versionskompatibilität aus. Im Nachfolgenden finden Sie unsere Vorgehensweise im Detail.
26 +== Search-API ==
26 26  
27 -Wir behalten (soweit technisch möglich) immer die zwei Versionen online. Sobald eine neue Version hinzukommt, wird die älteste Version mit einem zeitlichen Horizont von mindestens 6 Monaten abgekündigt. Nach der Abkündigung wird die Version und alle beinhalteten Minor-Versionen nicht mehr erreichbar sein.
28 +|(% style="width:250px" %)Zweck|Suchergebnisse, wie sie über die Benutzeroberfläche zu erlangen sind
29 +|Ausgabeformat|JSON
30 +|weitere Informationen|(((
31 +OpenAPI Spezifikation v3
28 28  
29 -Eine neue Major-Version kann Änderungen beinhalten, welche nicht mehr abwärtskompatibel sein müssen. Dies sind z.B.:
33 +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.
34 +)))
35 +|Dokumentation|[[Dokumentation Search-API>>path:/wiki/admindoku/view/Main/02_FSSchnittstellen/03_SearchAPI/]]
30 30  
31 -* Zugang
32 -* Endpunkte
33 -* Parameter
34 -* Response
37 +== Release-API ==
35 35  
36 -Eine neue Minor-Version ist per Definition abwärtskompatibel zur Major-Version. Dabei können Sie aber folgende Dinge ändern:
39 +|(% style="width:250px" %)Zweck|Veröffentlichungen auslesen; sowohl Assistenten als auch PDF-Formulare
40 +|Ausgabeformat|JSON; CSV
41 +|weitere Informationen|(((
42 +OpenAPI Spezifikation v3
37 37  
38 -* Zusätzliche Endpunkte
39 -* Weitere Parameter für eine Abfrage (z.B. Filterfunktion)
40 -* Erweitertes Response (weitere Ausgaben in der Antwort)
44 +Wir stellen mehrere Versionen der Release-API zur Verfügung.
45 +)))
46 +|Dokumentation|[[Dokumentation Release-API>>doc:.02_ReleaseAPI.WebHome]]
41 41  
42 -# Versionshistorie
48 +== (% style="color:inherit; font-family:inherit; font-size:max(20px, min(24px, 12.8889px + 0.925926vw))" %)Submission-API(%%) ==
43 43  
44 -Zu jeder API finden Sie als Unterknoten jeweils den "Release-Notes"-Artikel. Beispiel [[Submission-API|doc:.01_SubmissionAPI.Release-Notes.WebHome]].
50 +|(% style="width:250px" %)Zweck|Abruf von Informationen zu eingegangenen Formularen und von Formulardaten
51 +|Ausgabeformat|JSON
52 +|weitere Informationen|(((
53 +OpenAPI Spezifikation v3
54 +
55 +Einreichungen zu einem Formular/Artikelnummer für den Mandanten
56 +
57 +* Übersicht der Einreichungen (nur Metadaten)
58 +* Einschränkung der Suche
59 +** nach Bearbeitungsstatus (z.B. "NEW")
60 +** nach Einreichungszeitpunkt
61 +
62 +Spezifische Einreichungen
63 +
64 +* Abruf einer konkreten Einreichung
65 +** Metadaten
66 +** Inhalte
67 +* Änderung des Bearbeitungsstatus einer Einreichung
68 +
69 +Wir stellen mehrere Versionen der Submission-API zur Verfügung.
70 +)))
71 +|Versionshistorie|[[Submission-API Release-Notes>>doc:.01_SubmissionAPI.Release-Notes.WebHome]]
72 +|Dokumentation|[[Dokumentation Submission-API>>Main.02_FSSchnittstellen.01_SubmissionAPI]]
73 +
74 +== Error-API ==
75 +
76 +|(% style="width:250px" %)Zweck|Auflistung von Fehlern im Antragsprozess; alternativer Zugang zu Fehlerinformationen, ohne einen Formularserver-Administrator zu kontaktieren
77 +|Ausgabeformat|JSON
78 +|weitere Informationen|(((
79 +OpenAPI Spezifikation v3
80 +
81 +Während des Antragsprozesses kann der Assistent unerwartet auf einen Fehler laufen.
82 +
83 +Mit der Error-API stellt MACH formsolutions eine Lösung bereit, Fehlerursachen festzustellen, ohne einen Formularserver-Administrator zu kontaktieren.
84 +
85 +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.
86 +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.
87 +)))
88 +|Dokumentation|[[Dokumentation Error-API>>Main.02_FSSchnittstellen.04_ErrorAPI]]
89 +
90 += Unterstützung von Vorgängerversionen und abgekündigten APIs =
91 +
92 +* Die Dokumentation der „[[Search-API-Metaform>>Main.02_FSSchnittstellen.06_SearchAPIMetaform]]“
93 +* Die Dokumentation der „[[Massenverarbeitung von Formular-Eingängen-API>>Main.02_FSSchnittstellen.08_MassenverarbeitungAPI]]“
94 +* Die Dokumentation der „[[CMS-Schnittstelle>>Main.02_FSSchnittstellen.05_CMSSchnittstelle]]“
95 +* Die Dokumentation der „[[PDF Structure-API>>Main.02_FSSchnittstellen.07_PDFStructureAPI]]“
96 +
97 += Versionierung =
98 +
99 +Unsere APIs sind für eine lange Betriebsphase und Versionskompatibilität konzipiert.
100 +
101 +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.
102 +
103 +Eine neue **Major-Version (1.x)** kann Änderungen beinhalten, die nicht abwärtskompatibel sind. Dies sind z.B.:
104 +
105 +* Authentifizierungsmethoden
106 +* Umbenennung und Löschung von Endpunkten
107 +* Löschung von HTTP-Methoden an vorhandenen Endpunkten
108 +* Umbenennung und Löschung von Parametern
109 +* Restrukturierung des Response-Objekts
110 +
111 +Eine neue **Minor-Version (x.1)** ist definitionsgemäß abwärtskompatibel zur **Major-Version**. Änderungen wären z.B.:
112 +
113 +* Zusätzliche Endpunkte
114 +* Zusätzliche HTTP-Methoden an Endpunkten
115 +* Weitere (optionale) Parameter für eine Abfrage (z.B. Filterfunktion)
116 +* Erweitertes Response-Objekt