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 context-id (empty) The context the user is in
path integer user-id (empty) The ID representing the user
path integer limit (empty) Limits the output to a specific number of entries.
query integer sort (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 context-id (empty) The context the user is in
path integer user-id (empty) The ID representing the user
path integer provider-name (empty) The name of the provider to delete the device for
path string device-id (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 global (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 context-id (empty) The context the user is in
path integer user-id (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 context-id (empty) The context the user is in
path integer user-id (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 global (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 global (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 reseller (empty) The reseller name
query string package (empty) The package name
query string Body:
Description:JSONObject describing the advertisement configuration
Content-type: application/json-
string
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 reseller (empty) The reseller name
query string package (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 reseller (empty) The reseller's name
query string Body:
Description:JSONObject describing the advertisement configuration
Content-type: application/json-
string
Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
query long userId (empty) The user id
query long Body:
Description:JSONObject describing the advertisement configuration
Content-type: application/json-
string
Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
query long userId (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 name (empty) The user's login name
query string contextId (empty) The context id
query long Body:
Description:JSONObject describing the advertisement configuration
Content-type: application/json-
string
Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
-
Parameters:
Parameter Value Description Parameter Type Data Type name (empty) The user's login name
query string contextId (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
Examples:
Example: Get health statusGET http://localhost:8009/health -
-
-
InternetFreeBusy
Servlet for requesting free busy data.-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id of the context in which the requested user is located.
query integer userName (empty) The name of the user. Typically the local part of the email address.
query string server (empty) The name of the server. Typically the domain part of the email address.
query string weeksIntoPast (empty) The requested time range into the past in weeks. If this value is greater than the configured maximum, the free busy times are only requested to configured maximum. Default value is 1 week into the past.
query integer weeksIntoFuture (empty) The requested time range into the future in weeks. If this value is greater than the configured maximum, the free busy times are only requested to configured maximum. Default value is 4 week into the past.
query integer simple (empty) true, if the VFREEBUSY data should not contain free busy type and free information, false otherwise. Default value is false.
query boolean Responses:
200:
An iCalendar text containing the requested free busy data.
Content-type: text/calendar-
string
400:
In case one parameter is invalid.
404:
In case the servlet is not enabled, if no existing user with the requested user name, server and context id is found or if this user has not published his free busy data.
500:
In case an internal server error occurs.
-
-
-
Metrics
The metrics module-
Responses:
200:
The metrics in the prometheus format.
Content-type: text/plain-
string
401:
Not authorized
403:
In case basic authentication is enabled and an external client tries to access this resouce without using ssl.
-
-
-
Preliminary
This module contains preliminary endpoints which can change in the future.-
Body:
Description:JSONObject containing the push message
Content-type: application/json-
PushMessage object {
- event(string, optional): The event type.
-
user(string, optional):
The user identifier in the format
@ . E.g. 3@1 - folder(string, optional): The folder id
- imap-uid(string, optional): The mail uid
- from(string, optional): The from header of the mail
- subject(string, optional): The subject of the mail
- unseen(integer, optional): The number of unseen mails
- snippet(string, optional): A mail teaser
Responses:
200:
A JSON object with a success field set to 'true'.
Content-type: application/json-
SuccessResponse object {
- success(boolean, optional): No description available
401:
Not authorized
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
string
-
-
Parameters:
Parameter Value Description Parameter Type Data Type context (empty) The context id
path long user (empty) The user id
path long Responses:
200:
A JSON array containing the capabilities for the user
Content-type: application/json-
Capabilities array[object]An array of capabilities
401:
Not authorized
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
string
Examples:
Example: Get capabilitiesGET http://localhost:8009/preliminary/capabilities/v1/all/1/3 -
-
Parameters:
Parameter Value Description Parameter Type Data Type mail* (empty) The mail addresses as a semicolon separated list
path string Responses:
200:
A JSON array containing the capabilities for the user
Content-type: application/json-
stringA json object containg subobjects for every mail address which contains the user id, context id and addtional informations.
401:
Not authorized
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
string
Examples:
Example: Resolve addressesGET http://localhost:8009//preliminary/utilities/mailResolver/v1/resolve/anton@context1.ox.test;berta@context1.ox.test -
-
Parameters:
Parameter Value Description Parameter Type Data Type session (empty) The session id
path string Responses:
200:
A JSON object containing informations about the session.
Content-type: application/json-
objectA json object containing informations about the session.{
- context(integer, optional): The context id.
- user(integer, optional): The user id.
- guest(boolean, optional): Whether the session belongs to a guest user or not.
401:
Not authorized
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
string
Examples:
Example: Resolve sessionGET http://localhost:8009/preliminary/session/v1/get/1234567890 -
-
-
Userfeedback
The user feedback module-
Parameters:
Parameter Value Description Parameter Type Data Type context-group (empty) The context group identifying the global DB where the feedback is stored.
path string type (empty) The feedback type to send.
path string start (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 end (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
Examples:
Example: Export user feedback from 2016-01-01 to 2016-12-31GET http://localhost:8009/userfeedback/v1/export/default/star-rating-v1/raw?start=1451606400&end=1483228799 -
-
Parameters:
Parameter Value Description Parameter Type Data Type context-group (empty) The context group identifying the global DB where the feedback is stored.
path string type (empty) The feedback type to send.
path string start (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 end (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 delimiter (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
Examples:
Example: Export user feedback from 2016-01-01 to 2016-12-31 as CSVGET http://localhost:8009/userfeedback/v1/export/default/star-rating-v1?start=1451606400&end=1483228799 -
-
Parameters:
Parameter Value Description Parameter Type Data Type context-group (empty) The context group identifying the global DB where the feedback is stored.
path string type (empty) The feedback type to send.
path string start (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 end (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
Examples:
Example: Export user feedback from 2016-01-01 to 2016-12-31 and send it via mail to user1@example.org and user2@example.orgPOST http://localhost:8009/userfeedback/v1/send/default/star-rating-v1?start=1451606400&end=1483228799 {"subject":"User Feedback", "body":"User Feedback", "compress":true, "recipients": [ {"address":"user1@example.org", "displayName":"User 1", "pgp_key":"-----BEGIN PGP PUBLIC KEY BLOCK-----\r\nVersion: BCPG v1.56...."}, {"address":"user2@example.org", "displayName":"User 2", "pgp_key":"-----BEGIN PGP PUBLIC KEY BLOCK-----\r\nVersion: BCPG v1.56...."} ] } -
-
Parameters:
Parameter Value Description Parameter Type Data Type context-group (empty) The context group identifying the global DB where the feedback is stored.
path string type (empty) The feedback type to delete.
path string start (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 end (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
Examples:
Example: Delete user feedback from 2016-01-01 to 2016-12-31DELETE http://localhost:8009/userfeedback/v1/default/star-rating-v1?start=1451606400&end=1483228799 -
-