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"
]
}