The request URL for importing the channel configuration for a server has the following form:
/channels/by-server/<server ID>/import
The <server ID> has to be replaced by
the UUID associated with the respective server.
The request must use the POST method.
The request body must be a JSON object with the following members:
| Field name | Internal data type | JSON data type | Description |
|---|---|---|---|
| addChannels | boolean | boolean |
true if channels present in the
configuration file, but missing on the server shall be added
to the server.
false if no new channels shall be added to
the server.
Default is false.
|
| configurationFile | array of byte | string | Base64 (RFC 4648) encoded contents of the configuration file that shall be imported. |
| removeChannels | boolean | boolean |
true if channels missing in the
configuration file, but present on the server shall be removed
from the server.
false if no new channels shall be removed
from the server.
Default is false.
|
| simulate | boolean | boolean |
true if no modifications shall be made.
This means that the response will have the same content as if
all changes where applied successfully.
This is useful in combination with the
removeChannels option in order to see which
channels would be removed.
Default is false.
|
| updateChannels | boolean | boolean |
true if channels present in the
configuration file and also present on the server shall be
updated to match the configuration specified in the file.
false if no existing channels shall be
changed.
Default is false.
|
The response is a JSON object with the with the following members:
| Field name | Internal data type | JSON data type | Description |
|---|---|---|---|
| addOrUpdateFailed | map of string to string | object (with string attribute values) |
object with a member for each channels for which an add or
update operation failed.
The channel name is the member’s key and the corresponding
error message is the member’s value.
May be null if there is a global error or
if the data is sent in response to a request that has the
simulate flag set.
|
| addOrUpdateSucceeded | set of string | array of string |
list of channels for which an add or update operation was
successful.
In case of an update operation, this does not necessarily mean
that the server configuration has been updated.
It might also have already been identical to the configuration
specified by the file.
May be null if there is a global error.
|
| errorMessage | string | string |
error message indicating a global problem.
Such a problem does not affect a specific channel, but the
import process in general (e.g. a syntax error in the
configuration file).
If such an error is present, no changes have been made to the
server configuration.
null if there is no global error.
|
| removeFailed | map of string to string | object (with string attribute values) |
object with a member for each channel for which a remove
operation failed.
The channel name is the member’s key and the corresponding
error message is the member’s value.
May be null if there is a global error or
if the data is sent in response to a request that has the
simulate flag set.
|
| removeSucceeded | set of string | array of string |
list of channels for which a remove operation was successful.
May be null if there is a global error.
|
If there is a problem with the request parameters (e.g. a syntax eror
in the configuration file), HTTP error code 400 (bad request) is
returned.
If there is a general problem with the request body, the response body
is invalid.
If there only is a problem with the contents of the configuration
file, a valid JSON response with the errorMessage
set is returned.
If the user could not be authenticated or is not authorized to use
the import function, HTTP error code 403 (forbidden) is returned and
the response body is invalid.
If there is an error when applying the changes for at least one
channel, HTTP error code 500 (internal server error) is returned and
the channel is added to the addOrUpdateFailed or
removeFailed maps.
If there is a general problem while processing the request (e.g. the
database is currently unavailable), HTTP error code 503 (service
unavailable) is returned and the errorMessage is
set in the response.
Request:
POST /admin/api/1.0/channels/by-server/7cf8f393-cd00-46ae-9343-53e9cb5793fd/import
{
"addChannels": true,
"configurationFile": "PD94bWwgdmVy... (shortened for this example)",
"removeChannels": true
}
Response:
{
"addOrUpdateFailed": {
"someChannel": "Channel \"someChannel\" cannot be added because a channel
↪with the same name already exists."
},
"addOrUpdateSucceed": [
"newChannel"
],
"errorMessage": null,
"removeFailed": {},
"removeSucceeded": [
"someOtherChannel"
]
}