Profile API
Annotations and profiles enable the configuration and customization of the application.
In the following examples, the server https://www.myserver.com and the database test as well as the profile MyProfile are used for illustration purposes (e.g. in the path https://www.myserver.com/api/test/profiles/MyProfile).
The server and the database as well as the profile must be replaced accordingly in all actual requests.
Depending on the configuration, the URL may also have to be extended by the context path (e.g. https://www.myserver.com/dataspot/api/test/schemes/MyProfile).
The profile API is a programming interface that allows annotations and profiles to be imported and exported.
It is not possible to create new profiles with the profile API. Only existing annotations and profiles can be imported and exported.
Upload
A profile is uploaded with the HTTP method PUT at the following URL:
https://www.myserver.com/api/test/profiles/MyProfile/upload
The data is transferred as multipart/form-data.
The format is YAML.
The HTTP header attribute Content-Disposition defines the parameter name, describing the data, as well as the optional parameter filename, containing the original filename of the transferred file.
Content-Type: multipart/form-data
Content-Disposition: form-data; name="profile.yaml"; filename="MyProfile.yaml"
The response specifies whether the profile has been changed:
| HTTP message | Description |
|---|---|
true | The profile has been changed. |
false | The profile has not been changed. |
Only tenant annotations and tenant profiles can be imported. Standard annotations and standard profiles are delivered with the software and cannot be modified.
Usage
For the following examples the open source tool curl is used.
Alternatively, any library that can communicate over HTTP is also suitable.
The profile API requires appropriate login credentials (e.g. <user> and <password>).
Depending on the authentication method (Login ID and password, Single sign-on, Same sign-in, OpenID Connect) and used tools (e.g. curl), different mechanisms (e.g. basic authentication, bearer token) may be necessary to provide the credentials.
The user must exist and have administrator privileges.
Profile API upload
The profile API can be called with the HTTP method PUT to import a profile.
Using the option -F, the content of a file can be transferred as multipart/form-data.
curl -X PUT -u <user>:<password> -F <name>=@<filename> "https://www.myserver.com/api/test/profiles/MyProfile/upload"
Example: Profil import
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
A profile is downloaded with the HTTP method GET at the following URL:
https://www.myserver.com/api/test/profiles/MyProfile/download
The format is YAML (application/yaml).
Usage
For the following examples the open source tool curl is used.
Alternatively, any library that can communicate over HTTP is also suitable.
The profile API requires appropriate login credentials (e.g. <user> and <password>).
Depending on the authentication method (Login ID and password, Single sign-on, Same sign-in, OpenID Connect) and used tools (e.g. curl), different mechanisms (e.g. basic authentication, bearer token) may be necessary to provide the credentials.
The user must be authorized.
Profile API download
The profile API can be called with the HTTP method GET to export a profile.
curl -X GET -u <user>:<password> "https://www.myserver.com/api/test/profiles/MyProfile/download"
Example: Profil export
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"