Profile-API
Annotationen und Profile ermöglichen die Konfiguration und kundenspezifische Anpassung der Applikation.
In den nachfolgenden Beispielen werden zur Veranschaulichung der Server https://www.myserver.com und die Datenbank test sowie das Profil MyProfile verwendet (z.B. im Pfad https://www.myserver.com/api/test/profiles/MyProfile).
Der Server und die Datenbank sowie das Profil sind in allen echten Aufrufen entsprechend zu ersetzen.
Je nach Konfiguration muss die URL gegebenenfalls auch noch um den Context-Path erweitert werden (z.B. https://www.myserver.com/dataspot/api/test/profiles/MyProfile).
Das Profile-API ist eine Programmierschnittstelle, mit welcher Annotationen und Profile in YAML importiert und exportiert werden können.
Es ist nicht möglich, mit dem Profile-API neue Profile anzulegen. Es können ausschließlich bestehende Annotationen und Profile importiert und exportiert werden.
Upload
Der Upload eines Profils wird mit der HTTP-Methode PUT und folgender URL aufgerufen:
https://www.myserver.com/api/test/profiles/MyProfile/upload
Die Daten werden als multipart/form-data übertragen.
Das Format ist YAML.
Das HTTP-Header Attribut Content-Disposition definiert den Parameter name, um die Daten zu beschreiben, sowie den optionalen Parameter filename, welcher den ursprünglichen Dateinamen der übermittelten Datei enthält.
Content-Type: multipart/form-data
Content-Disposition: form-data; name="profile.yaml"; filename="MyProfile.yaml"
Die Antwort gibt an, ob das Profil geändert wurde:
| HTTP-Nachricht | Beschreibung |
|---|---|
true | Das Profil wurde geändert. |
false | Das Profil wurde nicht geändert. |
Nur Mandanten-Annotationen und Mandanten-Profile können importiert werden. Standard-Annotationen und Standard-Profile werden mit der Software ausgeliefert und können nicht geändert werden.
Aufruf
Für die nachfolgenden Beispiele wird das Open-Source Tool curl verwendet.
Alternativ ist jede beliebige Bibliothek geeignet, die über HTTP kommunizieren kann.
Für die Aufrufe sind Zugangsdaten (z.B. <user> und <password>) erforderlich.
Je nach Authentifizierungsmethode (Benutzerkennung und Passwort, Single Sign-On, Same Sign-In, OpenID Connect) und eingesetzten Tools (z.B. curl) können unterschiedliche Mechanismen (z.B. Basic Authentication, Bearer Token) notwendig sein, um die Zugangsdaten bereitzustellen.
Der entsprechende Benutzer muss erfasst und als Administrator berechtigt sein.
Profile-API Upload
Das Profile-API kann mit der HTTP-Methode PUT aufgerufen werden, um ein Profil zu importieren.
Der Inhalt einer Datei kann mit der Option -F als multipart/form-data übertragen werden.
curl -X PUT -u <user>:<password> -F <name>=@<filename> "https://www.myserver.com/api/test/profiles/MyProfile/upload"
Beispiel: Profil importieren
curl -X PUT -u jdoe:s3cr3t -F profile.yaml=@MyProfile.yaml "https://www.myserver.com/api/test/profiles/MyProfile/upload"
PUT /api/test/profiles/MyProfile/upload HTTP/1.1
Host: www.myserver.com
Content-Type: multipart/form-data
Content-Disposition: form-data; name="profile.yaml"; filename="MyProfile.yaml"
HTTP/1.1 200 OK
Content-Type: application/json
true
Download
Der Download eines Profils wird mit der HTTP-Methode GET und folgender URL aufgerufen:
https://www.myserver.com/api/test/profiles/MyProfile/download
Das Format ist YAML (application/yaml).
Aufruf
Für die nachfolgenden Beispiele wird das Open-Source Tool curl verwendet.
Alternativ ist jede beliebige Bibliothek geeignet, die über HTTP kommunizieren kann.
Für die Aufrufe sind Zugangsdaten (z.B. <user> und <password>) erforderlich.
Je nach Authentifizierungsmethode (Benutzerkennung und Passwort, Single Sign-On, Same Sign-In, OpenID Connect) und eingesetzten Tools (z.B. curl) können unterschiedliche Mechanismen (z.B. Basic Authentication, Bearer Token) notwendig sein, um die Zugangsdaten bereitzustellen.
Der entsprechende Benutzer muss berechtigt sein.
Profile-API Download
Das Profile-API kann mit der HTTP-Methode GET aufgerufen werden, um ein Profil zu exportieren.
curl -X GET -u <user>:<password> "https://www.myserver.com/api/test/profiles/MyProfile/download"
Beispiel: Profil exportieren
curl -X GET -u jdoe:s3cr3t -o MyProfile.yaml "https://www.myserver.com/api/test/profiles/MyProfile/download"
GET /api/test/profiles/MyProfile/download HTTP/1.1
Host: www.myserver.com
HTTP/1.1 200
Content-Type: application/yaml
Content-Disposition: filename="MyProfile.yaml"