Wiki-Quellcode von Server-Information-API
Version 1.1 von MACH ProForms GmbH am 16.12.2021
Zeige letzte Bearbeiter
| author | version | line-number | content |
|---|---|---|---|
| 1 | ## Allgemeines | ||
| 2 | |||
| 3 | Form-Solutions stellt eine Schnittstelle zur Verfügung, die es ermöglicht, allgemeine Informationen | ||
| 4 | über den Server und die verfügbaren Schnittstellen auszulesen. | ||
| 5 | |||
| 6 | ## Voraussetzungen | ||
| 7 | |||
| 8 | Um die Server-API nutzen zu können sind folgende Voraussetzungen zu erfüllen: | ||
| 9 | |||
| 10 | - Der Formularserver benötigt mindestens das Release mit der Version 4.73.0 | ||
| 11 | - Es muss für die Authentifizierung die Mandantennummer und der API-Key vorhanden sein. | ||
| 12 | |||
| 13 | ## Verwendung der Schnittstelle | ||
| 14 | |||
| 15 | Da die Schnittstelle auf dem REST-Standard beruht, kann diese über eine URL erreicht werden. Hierbei | ||
| 16 | gibt es einen festen Basispfad und einen entsprechenden Endpunkt. Der Basispfad ist bei jedem Aufruf | ||
| 17 | gleich, wobei sich die Endpunkte je nach Funktion unterscheiden können. Ein Endpunkt spricht eine | ||
| 18 | Funktionalität der Schnittstelle an. Da der Basispfad immer gleich ist, können über diverse Endpunkte | ||
| 19 | mehrere Funktionalitäten in die Schnittstelle verbaut werden. Weitere Verwendungsmöglichkeiten | ||
| 20 | finden Sie in der entsprechenden [[Swagger-Dokumentation|1]] | ||
| 21 | |||
| 22 | ## Einschränkungen | ||
| 23 | |||
| 24 | Die API wurde nicht für den Browser gebrauch konzipiert. Um die Anbindung zu testen, werden externe Tools | ||
| 25 | wie beispielsweise [[Insomnia|2]] oder [[Postman|3]] empfohlen. | ||
| 26 | |||
| 27 | ## Ausgabeformate | ||
| 28 | |||
| 29 | Die Schnittstelle gibt Daten im JSON-Format aus. | ||
| 30 | |||
| 31 | ## Authentifizierung | ||
| 32 | |||
| 33 | Um die Schnittstelle verwenden zu können, muss eine Authentifizierung vorgenommen werden. Für diese ist die | ||
| 34 | Mandantennummer und der dafür hinterlegte API-Schlüssel notwendig, wobei die Mandantennummer als | ||
| 35 | Benutzername und der API-Schlüssel als Passwort gilt. Sollte noch kein passender API-Schlüssel vorliegen, | ||
| 36 | kann dieser beim Administrator des Fomularservers beantragt werden. | ||
| 37 | |||
| 38 | Die erforderlichen Authentifizierungsdaten dienen zu Demonstrationszwecken und lauten wie folgt: | ||
| 39 | |||
| 40 | - ***Mandantennummer:*** 77777777-0000 | ||
| 41 | - ***API-Schlüssel:*** yIJNM2BS6LI0lS25Qa5xbtEK | ||
| 42 | |||
| 43 | > {{icon name="far fa-info-circle" size="3"/}} ***Hinweis:*** | ||
| 44 | > Die Authentifizierung ist nur mit HTTP-Basic möglich. | ||
| 45 | |||
| 46 | ## Beispielanwendung (Swagger-Dokumentation) | ||
| 47 | |||
| 48 | Um die Schnittstelle beispielhaft bedienen zu können, wird eine [[Demoanwendung|1]] bereitgestellt. | ||
| 49 | |||
| 50 | > ***Achtung*** | ||
| 51 | > Die oben verlinkte Swagger-Dokumentation greift auf den Form-Solutions internen Vertriebsserver | ||
| 52 | > zu. Um die Dokumentation auf anderen Servern einzusehen muss die URL folgendem Format entsprechen: | ||
| 53 | > `< BASIS_URL >/server/api/swagger-ui.html` | ||
| 54 | |||
| 55 | Ebenso steht dem Anwender mit dieser Beispielanwendung eine technische Dokumentation zur Verfügung, | ||
| 56 | welche die einzelnen Ressourcen detaillierter beschreibt. | ||
| 57 | |||
| 58 | [1](https://vertrieb.form-solutions.de/server/api/swagger-ui.html) | ||
| 59 | [2](https://insomnia.rest/) | ||
| 60 | [3](https://www.postman.com/) |