Introduction

This pages describes the HTTP API of the OX Middleware.

Low level protocol

The client accesses the server through HTTP GET, POST and PUT requests. HTTP cookies are used for authentication and must therefore be processed and sent back by the client as specified by RFC 6265. The HTTP API is accessible at URIs starting with /ajax. Each server module has a unique name and its own sub-namespace with that name below /ajax, e. g. all access to the module "tasks" is via URIs starting with /ajax/tasks.

Text encoding is always UTF-8. Data is sent from the server to the client as text/javascript and interpreted by the client to obtain an ECMAScript object. The HTTP API uses only a small subset of the ECMAScript syntax. This subset is roughly described by the following BNF:

Value	::= "null" | Boolean | Number | String | Array | Object
Boolean	::= "true" | "false"
Number	::= see NumericLiteral in ECMA 262 3rd edition
String	::= \"([^"\n\\]|\\["\n\\])*\"
Array	::= "[]" | "[" Value ("," Value)* "]"
Object	::= "{}" | "{" Name ":" Value ("," Name ":" Value)* "}"
Name	::= [A-Fa-f][0-9A-Fa-f_]*

Numbers are the standard signed integer and floating point numbers. Strings can contain any character, except double quotes, newlines and backslashes, which must be escaped by a backslash. Control characters in strings (other than newline) are not supported. Whitespace is allowed between any two tokens. See JSON and ECMA 262, 3rd edition for the formal definition.

The response body consists of an object, which contains up to four fields as described in Response body. The field data contains the actual payload which is described in following chapters. The fields timestamp, error and error_params are present when data objects are returned, if an error occurred and if the error message contains conversion specifiers, respectively. Following sections describe the contents of these fields in more detail.

The following table shows the different category identifiers:

Data from the client to the server can be sent in several formats. Small amounts of data are sent as application/x-www-urlencoded in query parameters in the request URI. For POST requests, some or all parameters may be sent in the request body instead of in the URI using any valid encoding for POST requests. Alternatively, some requests specify that data is sent as text/javascript in the body of a PUT request. The format of the request body for PUT requests is the same as for sending data from the server to the client, except that the payload is sent directly, without being wrapped in another object.

When updating existing data, the client sends only fields that were modified. To explicitly delete a field, the field is sent with the value null. For fields of type String, the empty string "" is equivalent to null.

Error handling

If the session of the user times out, if the client doesn't send a session ID or if the session for the specified session ID can not be found then the server returns the above described response object, that contains an error code and an error message. If the request URI or the request body is malformed or incomplete then the server returns the reponse object with an error message, too. In case of internal server errors, especially Java exceptions, or if the server is down, it returns the HTTP status code 503, Service Unavailable. Other severe errors may return other HTTP status values.

Application errors, which can be caused by a user and are therefore expected during the operation of the groupware, are reported by setting the field error in the returned object, as described in the Response body. Since the error messages are translated by the client, they can not be composed of multiple variable parts. Instead, the error message can contain simplified printf()-style conversion specifications, which are replaced by elements from the array in the field error_params. If error_params is not present, no replacement occurs, even if parts of the error message match the syntax of a conversion specification.

A simplified conversion specification, as used for error messages, is either of the form %s or %n$s_, where _n_ is a 1-based decimal parameter index. The conversion specifications are replaced from left to right by elements from `error_params`, starting at the first element. _%s_ is replaced by the current element and the current index is incremented. _%n$s is replaced by the n'th element and the current index is set to the (n + 1)'th element.

Some error message contain data sizes which must be expressed in Bytes or Kilobytes etc., depending on the actual value. Since the unit must be translated, this conversion is performed by the client. Unfortunately, standard printf()-style formatting does not have a specifier for this kind of translation. Therefore, the conversion specification for sizes is the same as for normal strings, and the client has to determine which parameters to translate based on the error code. The current error codes and the corresponding size parameters are listed below:

Date and time

Dates without time are transmitted as the number of milliseconds between 00:00 UTC on that date and 1970-01-01 00:00 UTC. Leap seconds are ignored, therefore this number is always an integer multiple of 8.64e7.

Because ECMAScript Date objects have no way to explicitly specify a timezone for calculations, timezone correction must be performed on the server. Dates with time are transmitted as the number of milliseconds since 1970-01-01 00:00 UTC (again, ignoring leap seconds) plus the offset between the user's timezone and UTC at the time in question. (See the Java method java.util.TimeZone.getOffset(long)). Unless optional URL parameter timezone is present. Then dates with time are transmitted as the number of milliseconds since 1970-01-01 00:00 UTC (again, ignoring leap seconds) plus the offset between the specified timezone and UTC at the time in question.

For some date and time values, especially timestamps, monotonicity is more important than the actual value. Such values are transmitted as the number of milliseconds since 1970-01-01 00:00 UTC, ignoring leap seconds and without timezone correction. If possible, a unique strictly monotonic increasing value should be used instead, as it avoids some race conditions described below.

This specification refers to these three interpretations of the type Number as separate data types.

Updates

To allow efficient synchronization of a client with changes made by other clients and to detect conflicts, the server stores a timestamp of the last modification for each object. Whenever the server transmits data objects to the client, the response object described in Response body includes the field timestamp. This field contains a timestamp value which is computed as the maximum of the timestamps of all transmitted objects.

When requesting updates to a previously retrieved set of objects, the client sends the last timestamp which belongs to that set of objects. The response contains all updates with timestamps greater than the one specified by the client. The field timestamp of the response contains the new maximum timestamp value.

If multiple different objects may have the same timestamp values, then a race condition exists when an update is processed between two such objects being modified. The first, already modified object will be included in the update response and its timestamp will be the maximum timestamp value sent in the timestamp field of the response. If the second object is modified later but gets the same timestamp, the client will never see the update to that object because the next update request from the client supplies the same timestamp value, but only modifications with greater timestamp values are returned.

If unique sequence numbers can't be used as timestamps, then the risk of the race condition can be at least minimized by storing timestamps in the most precise format and/or limiting update results to changes with timestamp values which are measurably smaller than the current timestamp value.

Editing

Editing objects is performed one object at a time. There may be multiple objects being edited by the same client simulataneously, but this is achieved by repeating the steps required for editing a single object. There is no batch edit or upload command.

To edit an object, a client first requests the entire object from the server. The server response contains the timestamp field described in the previous section. For in-place editing inside a view of multiple objects, where only already retrieved fields can be changed, retrieving the entire object is not necessary, and the last timestamp of the view is used as the timestamp of each object in it.

When sending the modified object back to the server, only modified fields need to be included in the sent object. The request also includes the timestamp of the edited object. The timestamp is used by the server to ensure that the object was not edited by another client in the meantime. If the current timestamp of the object is greater than the timestamp supplied by the client, then a conflict is detected and the field error is set in the response. Otherwise, the object gets a new timestamp and the response to the client is empty.

If the client displays the edited object in a view together with other objects, then the client will need to perform an update of that view immediately after successfully uploading an edited object.

File uploads

File uploads are made by sending a POST request that submits both the file and the needed fields as parts of a request of content-type “multipart/form-data” or “multipart/mixed”. The file metadata are stored in a form field “file” (much like an <input type=”file” name=”file” /> would do). In general a call that allows file uploads via POST will have a corresponding call using PUT to send object data. The JSON-encoded object-data that is send as the body of a corresponding PUT call is, when performed as a POST with file uploads, put into the request parameter “json”.

Since the upload is performed directly by the browser and is not an Ajax call, the normal callback mechanism for asynchronous Javascript calls cannot be used to obtain the result. For this reason the server responds to these POST calls with a complete HTML page that performs the callback and should not be displayed to the user. The HTML response is functionally equivalent to:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <META http-equiv="Content-Type" content=\"text/html; charset=UTF-8\">
    <script type="text/javascript">
      (parent["callback_action"] || window.opener && window.opener["callback_action"])
      ({json})
    </script>
  </head>
</html>

The placeholders {json} is replaced by the response with the timestamp that would be expected from the corresponding PUT method. The placeholder action is replaced by the value of the parameter action of the request (except for the import bundle, which is named "import" instead of the action name for legacy purposes). The content-type of the answer is text/html.

Non-browser clients don't need to interpret HTML or JavaScript. The JSON data can be recognized by the outermost ({ and }), where the inner braces are part of the JSON value. For example, the regular expression \((\{.*\})\) captures the entire JSON value in its first capturing group.

The client can also send the force_json_response parameter to get errors in form of a normal json responses instead of html.

Column identifiers

Below you find the identifiers for object fields of certain data objects (models) that can be used in the columns parameter of a request to return specific field data of single or multiple objects.

Common object data

Permission object

Extended permission object

Common folder data

Detailed folder data

Type of folder

Detailed task and appointment data

Task sequence type

Participant identifier

Participant types

User participant object

Confirmation status

Confirming participant

Detailed task data

Task status

Detailed contact data

Distribution list member

Mail fields

Detailed appointment data

Appointment availability

Detailed mail data

Mail system flags

X-Priority header

Attachment

Detailed infoitem data

Object Permission object

Extended object permission object

Object permission flags

|Bits | Value | |0 |The numerical value indicating no object permissions.| |1 | The numerical value indicating read object permissions.| |2 | The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).|

Attachment object

Attachment module

Mail account data

Credential source

Detailed user data

Messaging message columns

Group data

Flags and bitmasks

Permission flags

Capabilities

Note: Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.

Standard Folder Types

Supported Capabilities

Mail filter

This chapter gives a detailed description of the mail filter module. It should be uses as a source of information in addition to the http api.

First of all the main structure of a mail filter script is, that it has different rules. Each of them contains one command. This command takes a test condition which executes the actions given in that command if the test condition is true.

The test condition consists of a test command and some arguments for this command depending on the command itself. Because the available tests depend on the mail filter server, these tests must be determined at runtime. So that no test field is transferred to the server which it isn't able to handle. Examples for tests are address, allof and anyof.

Each test has a special comparison. The list of available comparisons depends on the test given and the mail filter server configuration so they have to be determined at runtime too.

Each time you want to do some action on a mail you need a so called action command. This describes what to do with a mail. To action commands the same applies as to the test commands and their comparison types, they must be determined at runtime.

All those dynamical values can be fetched via a config object at startup. This object shows the capabilities of the server to the client. This allows the client to show only the capabilities the server actually has to the user and to send only objects to the server which produce no errors on the server side.

To deal with this high flexibility of mail filters this specification can be roughly divided into 2 parts. A non-changing core and dynamical extensions. The core specification is that each rule consists of a name, an ID, a value showing if this rule is active or not and a tag which can be set on a rule to mark that rule for a special purpose. Furthermore each rule takes a test object, specifying in what case the following actions are triggered, and one or many actioncommands, specifying the actions itself.

The objects for the tests and the actions are dynamical, so the set presented in this specification may be changed over the time, but only compatible changes are allowed to the objects, otherwise new test or action objects have to be introduced. Due to the fact that not every sieve implementation will offer all the capabilities written in this document, the server will sent his configuration if a special request is made. This configuration will show which of the tests and which of the actions are allowed. So for example if the server signals that it is capable of handling vacation, sending a vacation object as action is safe.

Furthermore some tests use a comparison field as stated above which specifies how the fields are compared. The values of this field must also be determined at runtime. So in the configuration object there is a special part which shows the comparisons which are available. Note that not all comparisons can be used with every test. Some of them are denoted to a special test, which is described in Possible comparisons.

Possible tests

Simplified tests

The mailfilter v2 api suppports some simplified rules.

Possible comparisons

Possible currentdate comparisons

Possible address parts

Possible size comparisons

Possible extensions

Structure of tests

This section describes the structures of tests.

address-test

envelope-test

true-test

not-test

size-test

currentdate-test

header-test

allof-test

anyof-test

body-test

date-test

exists-test

simplified-header-test

Possible action commands

Structure of action commands

This section describes the structures of action commands.

keep-command

discard-command

redirect-command

move-command

reject-command

stop-command

vacation-command

addflags-command

setflags-command

Flags

notify-command

pgp-command

Advanced Search

This chapter describes the search module in more detail. Each search request contains a JSON object representing the search term. The search term is embedded in a wrapping JSON object with the field filter, like {"filter":[search term]}. In general the structure of a search term is in prefix notation, meaning the operator is written before its operands: [">", 5, 2] represents the condition "5 > 2".

Operators

There are two kinds of search operators, comparison operators and logic operators.

Comparison operators

Comparison operators compare two operands with one another. The exception is the "isNull" operator which has only one operand which must be a field name. The following operators are available:

Logic operators

Logic operators combine search expressions. Whereby the logic operator "not" has exactly one operand, the other logic operators can have any number of operands. Each operand must be an array representing a nested search expression.

Operands

Each operator needs one or more operands. There are different types of operands:

• Constant
• Field
• Attachment
• Header

Constant

Primitive JSON types are interpreted as constants, but arrays are not valid operands for comparison operators!

Field

A field operand is a JSON object with the member field specifying the field name, e.g. {"field":"first_name"}. The available field names depend on the module that implements the search.

Attachment

A attachment operand is a JSON object with the member attachment specifying the attachment name, e.g. {"attachment":"somedocument.txt"}. The attachment search is only available in case the FILENAME_SEARCH capability is included in the list of supported_capabilities of the folder.

Header

A header operand is a JSON object with the member header specifying the header name, e.g. {"header":"From"}.

Examples

{
  "filter":[
    "and",
    [
      "=",
      {
        "field":"field_name1"
      },
      "value1"
    ],
    [
      "not",
      [
        ">",
        {
          "field":"field_name2"
        },
        "value2"
      ]
    ]
  ]
}

Represents the expression field_name1 = value1 AND NOT field_name2 > value2.

Calendar account configuration

This chapter describes the configuration of different calendar accounts.

ICal feeds

Various ICal feeds can be subscribed by the given URI and optional basic authentication.

For example:

{
  "configuration":{
    "uri":"http://example.org/feed/theExampleFeed.ics"
  }
}

If basic authentication is required the body should contain 'login', 'password' or both as desired by the endpoint, for instance:

{
  "configuration":{
    "uri":"http://example.org/feed/theSecureExampleFeed.ics"
    "login":"johnDoe",
    "password":"myPassword"
  }
}

Google

The google calendar account basically only needs the id of a valid google oauth account with the calendar_ro scope.

For example:

{
  "configuration":{
    "oauthId":5
  }
}

This way the middleware creates a google calendar account which uses the given oauth account. During the initialization of the account the folders field is filled with all available google calendars. This json object contains another json objects for each calendar, whereby the key of each entry is the id of the google calendar (E.g. test_account@gmail.com). Each google calendar object contains different informations about the calendar (e.g. the color, default reminders etc.). But the most important field is the enabled field which defines whether a google calendar is subscribed or not. By default only the primary account is enabled (and therefore subscribed). If the client wants to enable other accounts too, it can do so by setting the enabled field to true and updating the account.

Example configuration after creation:

 "configuration": {
            "oauthId": 41,
            "folders": {
                "test_account@gmail.com": {
                    "enabled": true,
                    "color": "#9fe1e7",
                    "default_reminders": [
                        {
                            "action": "DISPLAY",
                            "duration": "-PT30M"
                        }
                    ],
                    "primary": true
                },
                "#contacts@group.v.calendar.google.com": {
                    "enabled": false,
                    "color": "#92e1c0",
                    "default_reminders": []
                },
                "en.german#holiday@group.v.calendar.google.com": {
                    "enabled": false,
                    "color": "#16a765",
                    "default_reminders": []
                },
                "e_2_en#weeknum@group.v.calendar.google.com": {
                    "enabled": false,
                    "color": "#42d692",
                    "default_reminders": []
                }
            }
        }

Config module

The config module is used to retrieve and set user-specific configuration. The configuration is stored in a tree. Each node of the tree has a name and a value. The values of leaf nodes are strings which store the actual configuration data. The values of inner nodes are defined recursively as objects with one field for each child node. The name and the value of each field is the name and the value of the corresponding child node, respectively.

The namespace looks like the following:

• /ajax/config/
• gui – A string containing GUI-specific settings (currently, it is a huge JSON object).
• fastgui - A string containing GUI-specific settings. This is a JSON object that must be kept small for performance.
• context_id - the unique identifier of the context (read-only).
• cookielifetime - the cookie life time in seconds or -1 for session cookie (read-only).
• identifier – the unique identifier of the user (read-only).
• contact_id – the unique identifier of the contact data of the user (read-only).
• language – the configured language of the user.
• timezone – the configured timezone of the user.
• availableTimeZones – a JSON object containing all available time zones. The key is the time zone identifier and the value contains its name in users language. (read-only).
• reloadTimes - Selectable times for GUI reload
• serverVersion - Version string of the server.
• currentTime - User timezone specific long of the current server time.
• maxUploadIdleTimeout - Timeout after that idle uploads are deleted.
• folder/ – the standard folder of the user
  • tasks – the standard task folder (read-only)
  • calendar – the standard calendar folder (read-only)
  • contacts – the standard contacts folder (read-only)
  • infostore – the private infostore folder (read-only)
  • eas – whether EAS folder selection is enabled (read-only)
• participants
  • autoSearch - If a search for all users, groups and resources when participant selection dialog is opened. (read-only)
  • showWithoutEmail - If external participants without email should be shown.
  • showDialog – Enables participant selection dialog for appointments and tasks. (read-only)
• availableModules – Contains a JSON array listing all enabled modules for a user. GUI loads Plugins through this list. To get your plugin listed here, create a subtree below modules/ without a module * subelement or with a subelement containing true (read-only)
• minimumSearchCharacters – Minimum number of characters a search pattern must have to prevent large responses and slow queries. (read-only)
• modules
  • portal
  • gui GUI settings for portal module
  • module
  • mail
  • addresses – all email addresses of the user including the primary address (read-only)
  • appendmailtext
  • allowhtmlimages – Alters default setting whether external images contained in HTML content are allowed or not
  • colorquoted – color quoted lines
  • contactCollectFolder – contact folder id to save mail addresses from sent mails
  • contactCollectEnabled – switch contact collection on/off
  • contactCollectOnMailAccess – enables/disables contact collection for incoming mails. Default is true.
  • contactCollectOnMailTransport – enables/disables contact collection for outgoing mails. Default is true.
  • defaultaddress – primary email address of the user (read-only)
  • deletemail – delete emails or move to trash
  • emoticons – display emoticons as graphics
  • defaultFolder
    • drafts – identifier of the folder with the mail drafts (read-only)
    • inbox – identifier of the folder that gets all incoming mails (read-only)
    • sent – identifier of the folder with the sent mails (read-only)
    • spam – identifier of the folder with the spam mails (read-only)
    • trash – identifier of the folder with the deleted mails (read-only)
  • forwardmessage – forward messages as inline or attachment
  • gui GUI settings for mail module
  • inlineattachments – activate inlining of HTML attachments
  • linewrap
  • module – if mail module is enabled or not
  • phishingheaders – header(s) identifying phishing headers
  • replyallcc – put all recipients on reply all into CC
  • sendaddress – one email address out of the addresses list that are email sent with
  • spambutton – Spam Button should be displayed in GUI or not
  • vcard – attach vcard when sending mails
  • calendar
  • calendar_conflict
  • calendar_freebusy
  • calendar_teamview
  • gui GUI settings for the calendar module
  • module
  • notifyNewModifiedDeleted receive mail notification for new, modified or deleted appointments
  • notifyAcceptedDeclinedAsCreator receive mail notification for accepted or declined appointments created by the user
  • notifyAcceptedDeclinedAsParticipant receive mail notification for accepted or declined appointments that the user participates
  • defaultStatusPrivate Default status for new appointments in private folders, where the user is participant. This does not affect appointments created by this user, which always have the status "accepted". The status are described in User participant object. Default is 0:none
  • defaultStatusPublic Default status for new appointments in public folders, where the user is participant. This does not affect appointments created by this user, which always have the status "accepted". The status are described in User participant object. Default is 0:none
  • contacts
  • gui GUI settings for the contacts module
  • mailAddressAutoSearch – Define if a search is triggered when the recipient selection dialog is opened or the folder is changed. (read-only)
  • module True if the contact module is enabled for the current user, false otherwise.
  • singleFolderSearch – True if the current user is allowed to search for contacts only in a single folder. False if contact searches across all folders are allowed. (read-only)
  • characterSearch – True if the side bar for searching for contacts by a start letter should be displayed. False if the side bar should be hidden. (read-only)
  • allFoldersForAutoComplete – true if an auto complete search may omit the folder identifier array and search for contacts in all readable folders. This is configured through the contact.properties configuration file. (read-only)
  • tasks
  • gui GUI settings for the tasks module
  • module
  • delegate_tasks
  • notifyNewModifiedDeleted receive mail notification for new, modified or deleted tasks
  • notifyAcceptedDeclinedAsCreator receive mail notification for accepted or declined tasks created by the user
  • notifyAcceptedDeclinedAsParticipant receive mail notification for accepted or declined taks that the user participates
  • infostore
  • gui GUI settings for the infostore module
  • folder – the standard infostore folders (read-only)
    • trash – identifier of the default infostore trash folder (read-only)
    • pictures – identifier of the default infostore pictures folder (read-only)
    • documents – identifier of the default infostore documents folder (read-only)
    • music – identifier of the default infostore music folder (read-only)
    • videos – identifier of the default infostore videos folder (read-only)
    • templates – identifier of the default infostore templates folder (read-only)
  • module
  • interfaces
  • ical
  • vcard
  • syncml
  • folder
  • gui UI settings for the folder tree
  • public_folders
  • read_create_shared_folders
  • tree – Selected folder tree, the user wants to use. Currents trees are 0 for the known OX folder tree and 1 for the new virtual folder tree.
  • com.openexchange.extras
  • module – Extras link in the configuration (read only)
  • com.openexchange.user.passwordchange
  • module – Will load Plug-In which allows to change the Password within the users configuration (read only)
  • com.openexchange.user.personaldata
  • module – Will load Plug-In which allows to edit personal contact information within the users configuration (read only)
  • com.openexchange.group
  • enabled – Specifies whether the user is allowed to edit groups and loads the corresponding Plug-In. (read only)
  • com.openexchange.resource
  • enabled – Specifies whether the user is allowed to edit resources and loads the corresponding Plug-In. (read only)
  • com.openexchange.publish
  • enabled – Specifies whether the user is allowed to publish items. (read only)
  • com.openexchange.subscribe
  • enabled – Specifies whether the user is allowed to subscribe sources. (read only)
  • olox20 [DEPRECATED]
  • active – Tells the UI if the user is allowed to use the OXtender for Microsoft Outlook 2. (read only)
  • module – Is set to false to prevent the UI from trying to load a plugin. (read only)
  • com.openexchange.oxupdater [DEPRECATED]
  • module – Is true if the OXUpdater package is installed and started. (read only)
  • active – Is true if the user is allowed to download the OXUpdater. Otherwise it's false. (read only)
  • com.openexchange.passwordchange
  • showStrength – Show a widget, which displays the current passwort Strength while entering. (default: false)
  • minLength – The minimum length of an entered password. (default: 4)
  • maxLength – The maximum length of an entered password. 0 for unlimited. (default: 0)
  • regexp – Defines the class of allowed special characters as Regular Expression. (default: [^a-z0-9])
  • special – Shows an example of allowed special characters to the user. Should be a subset of "regexp" in a human readable format. (default: $, _, or %)