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 master administrator credentials.

Security scheme type:	http
HTTP Authorization Scheme:	basic

OX REST API

Documentation of the Open-Xchange REST API.

Admin

Interface for provisioning and other administrative operations.

POST /admin/v1/close-sessions/by-context Close all sessions belonging to a context

Security:

This security scheme must be used:

Name	Scopes
masterAdminAuth

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
{
- contextIds ( array[integer] ): Array of context IDs
}

Responses:

200:

A JSON object containing all identifiers of the successfully closed sessions.

Content-type: application/json

CloseSessionsData
{
- closed ( array[string] ): 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.

POST /admin/v1/close-sessions/by-id Close a session by its ID

POST /admin/v1/close-sessions/by-user Close all sessions belonging to a user

GET /admin/v1/contexts/{context-id}/users/{user-id}/multifactor/devices Lists all multifactor authentication devices for a user.

Security:

This security scheme must be used:

Name	Scopes
contextAdminAuth

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
{
- id ( string ): The ID of the device
- name ( string ): The name of the device
- providerName ( string ): The name of the device's provider
- enabled ( boolean ): true, if the device is enabled, false if disabled
- backup ( boolean ): true, if the device is a backup device, false otherwise
}

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.

DELETE /admin/v1/contexts/{context-id}/users/{user-id}/multifactor/devices Deletes all multifactor authentication devices for a user.

DELETE /admin/v1/contexts/{context-id}/users/{user-id}/multifactor/devices/{provider-name}/{device-id} Deletes a multifactor authentication device.

GET /admin/v1/contexts/{context-id}/users/{user-id}/passwd-changes Lists the history of password changes for a user.

Security:

This security scheme must be used:

Name	Scopes
contextAdminAuth

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
{
- 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 ): 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 ): 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'.
}

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.

The advertisement module

PUT /advertisement/v1/config/name Sets an advertisement configuration for a given user by name

Parameter	Value	Description	Parameter Type	Data Type
name	(empty)	The user's login name	query	string
contextId	(empty)	The context id	query	long

DELETE /advertisement/v1/config/name Remove the current configuration for the user

Parameter	Value	Description	Parameter Type	Data Type
name	(empty)	The user's login name	query	string
contextId	(empty)	The context id	query	long

PUT /advertisement/v1/config/package Sets an advertisement configuration for a package of a reseller

Parameter	Value	Description	Parameter Type	Data Type
reseller	(empty)	The reseller name	query	string
package	(empty)	The package name	query	string

DELETE /advertisement/v1/config/package Remove the current configuration for a package of a reseller

Parameter	Value	Description	Parameter Type	Data Type
reseller	(empty)	The reseller name	query	string
package	(empty)	The package name	query	string

PUT /advertisement/v1/config/reseller Sets all advertisement configurations for a given reseller

Parameter	Value	Description	Parameter Type	Data Type
reseller	(empty)	The reseller's name	query	string

PUT /advertisement/v1/config/user Sets an advertisement configuration for a given user by id

Parameter	Value	Description	Parameter Type	Data Type
contextId	(empty)	The context id	query	long
userId	(empty)	The user id	query	long

DELETE /advertisement/v1/config/user Remove the current configuration for the user identified by userId

Health

The health-check module
- GET /health Get health status
  Responses:
  200:
  
  A JSON object containing health data
  
  Content-type: application/json
  
  HealthData
  {
  
  status ( string , possibleValues:
  
  UP
  
  DOWN
  
  ): The health overall status
  
  checks ( array[HealthCheckData] ): No description available
  
  service ( ServiceData ): No description available
  
  blacklist ( array[string] ): Blacklisted health checks
  
  ignorelist ( array[string] ): Ignored health checks
  
  }
  
  HealthCheckData
  {
  
  name ( string ): The health-check's name
  
  status ( string , possibleValues:
  
  UP
  
  DOWN
  
  ): The health-check's status
  
  data ( data ): JSON object containing health-check's additional data
  
  }
  
  ServiceData
  {
  
  name ( string ): The name
  
  version ( string ): The middleware version running on this node
  
  buildDate ( string ): The build date of the middleware running on this node
  
  date ( string ): The date the health-check was executed
  
  timeZone ( string ): The node's default time zone
  
  locale ( string ): The node's default locale
  
  charset ( string ): 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
  
  Unknown
  Examples:
  
  Example: Get health status
  GET http://localhost:8009/health

Parameter	Value	Description	Parameter Type	Data Type
contextId	(empty)	The context id	query	long
userId	(empty)	The user id	query	long

InternetFreeBusy

Servlet for requesting free busy data.

GET /servlet/webdav.freebusy Gets the free busy data in iCalendar format.

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

Unknown

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
- GET /metrics Gets appsuite metrics in the prometheus format
  Responses:
  200:
  
  The metrics in the prometheus format.
  
  Content-type: text/plain
  
  Unknown
  
  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.

GET /preliminary/capabilities/v1/all/{context}/{user} Gets all capabilities of a single user

PUT /preliminary/http-notify/v1/notify Used by the dovecot mail server to push messages to the server
Body:
Description:

JSONObject containing the push message

Content-type: application/json

PushMessage
{

event ( string , possibleValues:

messageNew

): The event type.

user ( string ): The user identifier in the format @. E.g. 3@1

folder ( string ): The folder id

imap-uid ( string ): The mail uid

from ( string ): The from header of the mail

subject ( string ): The subject of the mail

unseen ( integer ): The number of unseen mails

snippet ( string ): A mail teaser

}
Responses:
200:

A JSON object with a success field set to 'true'.

Content-type: application/json

SuccessResponse
{

success ( boolean ): 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

Unknown

Parameter	Value	Description	Parameter Type	Data Type
context	(empty)	The context id	path	long
user	(empty)	The user id	path	long

GET /preliminary/session/v1/get/{session} Resolves the given session id

Parameter	Value	Description	Parameter Type	Data Type
session	(empty)	The session id	path	string

GET /preliminary/utilities/mailResolver/v1/resolve/{mail*} Resolves the given mail addresses

Push

The push module
- PUT /chronos/v1/itip/pushmail Used by the dovecot mail server to push IMip Mails to the server
  Body:
  Description:
  
  JSONObject containing the push mail
  
  Content-type: application/json
  
  PushMail
  {
  
  event ( string , possibleValues:
  
  messageNew
  
  ): The event type.
  
  user ( string ): The user identifier in the format @, @ or the user's mail login.
  
  folder ( string ): The folder id
  
  body ( string ): The RFC822 Mail body
  
  }
  Responses:
  200:
  
  Empty repsonse.
  
  401:
  
  Not authorized
  
  500:
  
  In case of internal server error that might have multiple reasons. Response contains error message.
  
  Content-type: application/json
  
  Unknown

Parameter	Value	Description	Parameter Type	Data Type
mail*	(empty)	The mail addresses as a semicolon separated list	path	string

Userfeedback

The user feedback module

GET /userfeedback/v1/export/{context-group}/{type} Exports user feedback as CSV

Security:

This security scheme must be used:

Name	Scopes
basicAuth

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

Unknown

400:

Bad request, response contains error message.

Content-type: application/octet-stream

Unknown

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

Unknown

500:

Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.

Content-type: application/octet-stream

Unknown

Examples:

Example: Export user feedback from 2016-01-01 to 2016-12-31 as CSV

GET http://localhost:8009/userfeedback/v1/export/default/star-rating-v1?start=1451606400&end=1483228799

GET /userfeedback/v1/export/{context-group}/{type}/raw Exports user feedback

Security:

This security scheme must be used:

Name	Scopes
basicAuth

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

Unknown

400:

Bad request, response contains error message.

Content-type: application/json

Unknown

401:

Not authorized

404:

Not found, if path is wrong (unknown context group or feedback type). Response contains error message.

Content-type: application/json

Unknown

500:

Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.

Content-type: application/json

Unknown

Examples:

Example: Export user feedback from 2016-01-01 to 2016-12-31

GET http://localhost:8009/userfeedback/v1/export/default/star-rating-v1/raw?start=1451606400&end=1483228799

POST /userfeedback/v1/send/{context-group}/{type} Exports user feedback and sends exported data to provided recipients

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

Unknown
{
}

Responses:

200:

Info message about sent status

Content-type: */*

Unknown

400:

Bad request, response contains error message.

Content-type: */*

Unknown

401:

Not authorized

404:

Not found, if path is wrong (unknown context group or feedback type). Response contains error message.

Content-type: */*

Unknown

500:

Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.

Content-type: */*

Unknown

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.org

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

DELETE /userfeedback/v1/{context-group}/{type} Deletes user feedback

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

Unknown

400:

Bad request, response contains error message.

Content-type: application/json

Unknown

401:

Not authorized

404:

Not found, if path is wrong (unknown context group or feedback type). Response contains error message.

Content-type: application/json

Unknown

500:

Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.

Content-type: application/json

Unknown

Examples:

Example: Delete user feedback from 2016-01-01 to 2016-12-31

DELETE http://localhost:8009/userfeedback/v1/default/star-rating-v1?start=1451606400&end=1483228799

Introduction

Authentication

basicAuth

HTTP Basic Authentication.

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.

masterAdminAuth

The API can be accessed via HTTP Basic Auth with master administrator credentials.

OX REST API

Documentation of the Open-Xchange REST API.

Results

Admin

Security:

masterAdminAuth

Parameters:

Body:

Responses:

200:

400:

401:

403:

404:

500:

Security:

masterAdminAuth

Parameters:

Body:

Responses:

200:

400:

401:

403:

404:

500:

Security:

masterAdminAuth

Parameters:

Body:

Responses:

200:

400:

401:

403:

404:

500:

Security:

contextAdminAuth

Parameters:

Responses:

200:

401:

404:

500:

Security:

contextAdminAuth

Parameters:

Responses:

200:

401:

404:

500:

Security:

contextAdminAuth

Parameters:

Responses:

200:

401:

404:

500:

Security:

contextAdminAuth

Parameters:

Responses:

200:

400:

401:

404:

500:

Advertisement

Parameters: