Introduction
This page describes the rest http api. It provides interfaces for administrative purposes and is therefore not intended to be used by clients for endusers. Basic authentication is used to authenticate the client, which needs to be configured in the middleware via the following properties:
com.openexchange.rest.services.basic-auth.login
com.openexchange.rest.services.basic-auth.password
Authentication
basicAuth:
HTTP Basic Authentication.
| Security scheme type: | http |
| HTTP Authorization Scheme: | basic |
contextAdminAuth:
The API can be accessed via HTTP Basic Auth with context administrator credentials or reseller/master administrator credentials if MASTER_ACCOUNT_OVERRIDE is enabled.
| Security scheme type: | http |
| HTTP Authorization Scheme: | basic |
masterAdminAuth:
The API can be accessed via HTTP Basic Auth with reseller/master administrator credentials.
| Security scheme type: | http |
| HTTP Authorization Scheme: | basic |
OX REST API
Documentation of the Open-Xchange REST API.
Results
Test-
Admin
Interface for provisioning and other administrative operations.-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) The context the user is in
path integer (empty) The ID representing the user
path integer (empty) Limits the output to a specific number of entries.
query integer (empty) Comma sperated list of fields to sort the output for. Field names that begin with "-" will be sorted descending else the fields get sorted ascending. Valid fields are 'date' and 'client_id'.
query string Responses:
200:
An array of password change entries.
Content-type: application/json-
PasswordChangeHistoryEntry object {
- date(integer, required): Timestamp (milliseconds since 1970-01-01 00:00:00.000) of the change.
- client_id(string, required): Identifier of the client that was used to change the password. For example 'open-xchange-appsuite', 'provisioning-api'.
- client_address(string, optional): IP address of the client that was used to change the password. Only contained if it could be determined during the change.
- client_name(string, optional): Human-readable name of the client that was used to change the password. Only contained if the client ID has a known human-readable representation. If not set the client should fall-back to 'client_id'.
-
array[PasswordChangeHistoryEntry]
400:
Bad request, response contains error message.
401:
Not authorized
404:
Not found. If path is wrong. Response contains error message.
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) The context the user is in
path integer (empty) The ID representing the user
path integer (empty) The name of the provider to delete the device for
path string (empty) The ID of the device to delete
path string Responses:
200:
If the device was deleted
401:
Not authorized
404:
Not found. If path is wrong, or if the given provider, or device was not found.
500:
Internal server error that might have multiple reasons. Response contains error message.
-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) Close sessions cluster-wide. Default: true
query boolean Body:
Description:A JSON object containing an array of context ids.
Content-type: application/json-
CloseSessionsByContextBody object {
- contextIds(array[integer], optional): Array of context IDs
Responses:
200:
A JSON object containing all identifiers of the successfully closed sessions.
Content-type: application/json-
CloseSessionsData object {
- closed(array[string], optional): Array of the closed session identifiers
400:
Bad request, response contains error message.
401:
Not authorized
403:
Forbidden
404:
Not found. If path is wrong. Response contains error message.
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) The context the user is in
path integer (empty) The ID representing the user
path integer Responses:
200:
An array of multifactor devices.
Content-type: application/json-
MultifactorDeviceData object {
- id(string, optional): The ID of the device
- name(string, optional): The name of the device
- providerName(string, optional): The name of the device's provider
- enabled(boolean, optional): true, if the device is enabled, false if disabled
- backup(boolean, optional): true, if the device is a backup device, false otherwise
-
array[MultifactorDeviceData]
401:
Not authorized
404:
Not found. If path is wrong. Response contains error message.
500:
Internal server error that might have multiple reasons. Response contains error message.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) The context the user is in
path integer (empty) The ID representing the user
path integer Responses:
200:
All devices deleted
401:
Not authorized
404:
Not found. If path is wrong. Response contains error message.
500:
Internal server error that might have multiple reasons. Response contains error message.
-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) Close sessions cluster-wide. Default: true
query boolean Body:
Description:A JSON object containing an array of user and context id tuples.
Content-type: application/json-
CloseSessionByUserBody object {
- users(array[object], optional): Array of context/user id tuples
Responses:
200:
OK
400:
Bad request, response contains error message.
401:
Not authorized
403:
Forbidden
404:
Not found. If path is wrong. Response contains error message.
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) Close sessions cluster-wide. Default: true
query boolean Body:
Description:A JSON object containing an array of session ids.
Content-type: application/json-
CloseSessionsByIdBody object {
- sessionIds(array[string], optional): Array of session IDs
Responses:
200:
OK
400:
Bad request, response contains error message.
401:
Not authorized
403:
Forbidden
404:
Not found. If path is wrong. Response contains error message.
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
-
-
-
Advertisement
The advertisement module-
PUT /advertisement/v1/config/package Sets an advertisement configuration for a package of a reseller
Parameters:
Parameter Value Description Parameter Type Data Type (empty) The reseller name
query string (empty) The package name
query string Body:
Description:No description available
Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
DELETE /advertisement/v1/config/package Remove the current configuration for a package of a reseller
Parameters:
Parameter Value Description Parameter Type Data Type (empty) The reseller name
query string (empty) The package name
query string Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) The reseller's name
query string Body:
Description:No description available
Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) The context id
query long (empty) The user id
query long Body:
Description:No description available
Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) The context id
query long (empty) The user id
query long Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) The user's login name
query string (empty) The context id
query long Body:
Description:No description available
Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) The user's login name
query string (empty) The context id
query long Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
-
Health
The health-check module-
Responses:
200:
A JSON object containing health data
Content-type: application/json-
HealthData object {
- status(string, optional): The health overall status
- checks(array[HealthCheckData], optional): No description available
- service(ServiceData, optional): No description available
- blacklist(array[string], optional): Blacklisted health checks
- ignorelist(array[string], optional): Ignored health checks
-
HealthCheckData object {
- name(string, optional): The health-check's name
- status(string, optional): The health-check's status
- data(object, optional): JSON object containing health-check's additional data
-
ServiceData object {
- name(string, optional): The name
- version(string, optional): The middleware version running on this node
- buildDate(string, optional): The build date of the middleware running on this node
- date(string, optional): The date the health-check was executed
- timeZone(string, optional): The node's default time zone
- locale(string, optional): The node's default locale
- charset(string, optional): The node's default charset
401:
Not authorized
500:
In case of "DOWN"-result or internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
string
-
-
-
Userfeedback
The user feedback module-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) The context group identifying the global DB where the feedback is stored.
path string (empty) The feedback type to send.
path string (empty) Start time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given after this time is sent. If not set, all feedback up to -e is sent.
query long (empty) End time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given before this time is sent. If not set, all feedback since -s is sent.
query long Responses:
200:
A JSON array containing the stored user feedbacks.
Content-type: application/json-
string
400:
Bad request, response contains error message.
Content-type: application/json-
string
401:
Not authorized
404:
Not found, if path is wrong (unknown context group or feedback type). Response contains error message.
Content-type: application/json-
string
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
Content-type: application/json-
string
-
-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) The context group identifying the global DB where the feedback is stored.
path string (empty) The feedback type to send.
path string (empty) Start time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given after this time is sent. If not set, all feedback up to -e is sent.
query long (empty) End time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given before this time is sent. If not set, all feedback since -s is sent.
query long (empty) The column delimiter used. Default: ';'
query string Responses:
200:
Export data into a CSV file
Content-type: application/octet-stream-
string
400:
Bad request, response contains error message.
Content-type: application/octet-stream-
string
401:
Not authorized
404:
Not found, if path is wrong (unknown context group or feedback type). Response contains error message.
Content-type: application/octet-stream-
string
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
Content-type: application/octet-stream-
string
-
-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) The context group identifying the global DB where the feedback is stored.
path string (empty) The feedback type to send.
path string (empty) Start time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given after this time is sent. If not set, all feedback up to -e is sent.
query long (empty) End time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given before this time is sent. If not set, all feedback since -s is sent.
query long Body:
Description:JSONObject with fields "subject" for custom mail subject, "body" for custom mail body, boolean "compress" to compress the mail attachment and "recipients" (an JSON Array containing address, display name and PGP key (if available) for every recipient).
Content-type: application/json-
string
Responses:
200:
Info message about sent status
Content-type: */*-
string
400:
Bad request, response contains error message.
Content-type: */*-
string
401:
Not authorized
404:
Not found, if path is wrong (unknown context group or feedback type). Response contains error message.
Content-type: */*-
string
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
Content-type: */*-
string
-
-
Parameters:
Parameter Value Description Parameter Type Data Type (empty) The context group identifying the global DB where the feedback is stored.
path string (empty) The feedback type to delete.
path string (empty) Start time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given after this time is deleted. If not set, all feedback up to -e is deleted.
query long (empty) End time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given before this time is deleted. If not set, all feedback since -s is deleted.
query long Responses:
200:
Info message when successfull.
Content-type: application/json-
string
400:
Bad request, response contains error message.
Content-type: application/json-
string
401:
Not authorized
404:
Not found, if path is wrong (unknown context group or feedback type). Response contains error message.
Content-type: application/json-
string
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
Content-type: application/json-
string
-
-