Änderungen von Dokument Schnittstellen

Zusammenfassung

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

Details

Seiteneigenschaften

Titel

...	...	@@ -1,1 +1,1 @@
1		-Form-Solutions Schnittstellen
	1	+Schnittstellen

Syntax

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

Inhalt

...	...	@@ -1,10 +1,116 @@
1		-In diesem Teil der Dokumentation finden Sie:
2		-- Die Schnittstellendokumentation „[[rest-api|Main.02_FSSchnittstellen.01_rest-api]]“
3		-- Die Schnittstellenbeschreibung der [[CMS-Schnittstelle|Main.02_FSSchnittstellen.02_Services]]
4		-- Die Schnittstellenbeschreibung der Veröffentlichung „[[release-api|Main.02_FSSchnittstellen.03_ReleaseApi]]“
5		-- Die Schnittstellenbeschreibung der Suche „[[search-api|Main.02_FSSchnittstellen.04_searchApi]]“
	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.
6	6
7		-**Hinweis:**
8		-Die hier angegebenen Schnittstelleninformationen sollten noch aktuell sein, werden aber in absehbarer Zeit gegen neuere Versionen ausgetauscht, die auch wie andere Wiki-Seiten zu lesen sind.
	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.
9	9
10		-![[Schnittstellen|@Schnittstellen.jpg]]
	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]].
	9	+
	10	+(% class="box infomessage" %)
	11	+(((
	12	+Der Supermandant hat als übergeordnete Instanz Zugriff auf alle Mandanten.
	13	+)))
	14	+
	15	+{{toc/}}
	16	+
	17	+= Übersicht der APIs =
	18	+
	19	+== Server-Information-API ==
	20	+
	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]]
	25	+
	26	+== Search-API ==
	27	+
	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
	32	+
	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/]]
	36	+
	37	+== Release-API ==
	38	+
	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
	43	+
	44	+Wir stellen mehrere Versionen der Release-API zur Verfügung.
	45	+)))
	46	+|Dokumentation|[[Dokumentation Release-API>>doc:.02_ReleaseAPI.WebHome]]
	47	+
	48	+== (% style="color:inherit; font-family:inherit; font-size:max(20px, min(24px, 12.8889px + 0.925926vw))" %)Submission-API(%%) ==
	49	+
	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