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

• Admin

  Interface for provisioning and other administrative operations.
  Show/Hide List Operations Expand Operations

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

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

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

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

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

    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:

    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.

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

    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 user and context id tuples.

    Content-type: application/json

    
    
    • CloseSessionByUserBody
      {

      • users ( array[object] ): 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.

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

    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 session ids.

    Content-type: application/json

    
    
    • CloseSessionsByIdBody
      {

      • sessionIds ( array[string] ): 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
  Show/Hide List Operations Expand Operations

  • 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

    
    
    • Unknown
      

    
    

    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

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

    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

    
    
    • Unknown
      

    
    

    Responses:

    200:

    The configuration result

    400:

    Bad request, response contains error message.

    401:

    Not authorized

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

    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

    
    
    • Unknown
      

    
    

    Responses:

    200:

    The configuration result

    400:

    Bad request, response contains error message.

    401:

    Not authorized

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

    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

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

    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

    
    
    • Unknown
      

    
    

    Responses:

    200:

    The configuration result

    400:

    Bad request, response contains error message.

    401:

    Not authorized

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

    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
  Show/Hide List Operations Expand Operations

  • 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

  ---

• InternetFreeBusy

  Servlet for requesting free busy data.
  Show/Hide List Operations Expand Operations

  • 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
  Show/Hide List Operations Expand Operations

  • 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.
  Show/Hide List Operations Expand Operations

  • 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
      

    
    

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

    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

    
    

    401:

    Not authorized

    500:

    In case of internal server error that might have multiple reasons. Response contains error message.

    Content-type: application/json

    
    
    • Unknown
      

    
    

    Examples:

    Example: Get capabilities

    GET http://localhost:8009/preliminary/capabilities/v1/all/1/3

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

    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

    
    
    • Unknown - A 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

    
    
    • Unknown
      

    
    

    Examples:

    Example: Resolve addresses

    GET http://localhost:8009//preliminary/utilities/mailResolver/v1/resolve/anton@context1.ox.test;berta@context1.ox.test

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

    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

    
    
    • Unknown - A json object containing informations about the session.
      {

      • context ( integer ): The context id.
      • user ( integer ): The user id.
      • guest ( boolean ): 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

    
    
    • Unknown
      

    
    

    Examples:

    Example: Resolve session

    GET http://localhost:8009/preliminary/session/v1/get/1234567890

  ---

• Userfeedback

  The user feedback module
  Show/Hide List Operations Expand Operations

  • 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

  • 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

  • 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

  ---