| JMAP | N. Jenkins |
| Internet-Draft | FastMail |
| Intended status: Standards Track | October 19, 2016 |
| Expires: April 22, 2017 |
JSON Meta Application Protocol
draft-jenkins-jmap-00
This document specifies a protocol for synchronising JSON-based data objects efficiently, with support for push and out-of-band binary data upload/download.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 22, 2017.
Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
JMAP is a generic protocol for synchronising data, such as mail, calendars or contacts, between a client and a server. It is optimised for mobile and web environments, and aims to provide a consistent interface to different data types.
This specification is for the generic mechanism of authentication and synchronisation. Further specifications define the data models for different data types that may be synchronised via JMAP.
JMAP is designed to make efficient use of limited network resources. Multiple API calls may be batched in a single request to the server, reducing round trips and improving battery life on mobile devices. Push connections remove the need for polling, and an efficient delta update mechanism ensures a minimum of data is transferred.
JMAP is designed to be horizontally scalable to a very large number of users. This is facilitated by the separate end points for users after login, the separation of binary and structured data, and a shared data model that does not allow data dependencies between accounts.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
The underlying format used for this specification is JSON. Consequently, the terms "object" and "array" as well as the four primitive types (strings, numbers, booleans, and null) are to be interpreted as described in Section 1 of [RFC7159].
Some examples in this document contain "partial" JSON documents used for illustrative purposes. In these examples, three periods "..." are used to indicate a portion of the document that has been removed for compactness.
Types signatures are given for all JSON objects in this document. The following conventions are used:
A user represents a set of permissions relating to what data can be seen. To access data in JMAP, you first authenticate as a particular user.
An account is a collection of data.
All data, other than the Account objects themselves, belong to a single account. A single account may contain an arbitrary set of data, for example a collection of mail, contacts and calendars. Most operations in JMAP are isolated to a single account; there are a few explicit operations to copy data between them. Certain properties are guaranteed for data within the same account, for example uniqueness of ids within a type in that account.
An account is not the same as a user, although it is common for the primary account to directly belong to the user. For example, you may have an account that contains data for a group or business, to which multiple users have access. Users may also have access to accounts belonging to another user if that user is sharing some of their data.
JMAP provides a uniform interface for creating, retrieving, updating and deleting various types of objects. A data type is a collection of named, typed properties, just like the schema for a database table. Each instance of a data type is called a record.
All object ids are assigned by the server, and are immutable. They MUST be unique among all objects of the same type within the same account. Ids may clash across accounts, or for two objects of different types within the same account.
Ids are always Strings. An id MUST be a valid UTF-8 string of at least 1 character in length and maximum 256 bytes in size, but MUST NOT start with the # character, as this is reserved for doing back references during object creation (see the setFoos description).
JSON is a text-based data interchange format as specified in [RFC7159]. The I-JSON format defined in [RFC7493] is a strict subset of this, adding restrictions to avoid potentially confusing scenarios (for example, it mandates that an object MUST NOT have two properties with the same key).
All data sent from the client to the server or from the server to the client (except binary file upload/download) MUST be valid I-JSON according to the RFC, and is therefore case-sensitive and encoded in UTF-8.
All data exchanges are authenticated using an access token. Authentication is covered in section 2.
An authenticated client may exchange data with the server using four different mechanisms:
When connecting to any JMAP server, the client must first gain an access token. It cannot just use a username/password directly. This allows the server to know (and show the user) which clients currently have access to the account, and to be able to revoke access individually.
The server may support multiple different mechanisms for authenticating a user to gain the access token. It is expected that further types may be added in future extensions to the JMAP specification.
To begin authentication, the client needs to know the authentication URL for the JMAP server.
There are two standardised autodiscovery methods in use for internet protocols:
A JMAP-supporting host for the domain example.com SHOULD publish a SRV record _jmaps._tcp.example.com which gives a hostname and port (usually port 443). The authentication URL is then https://${hostname}[:${port}]/.well-known/jmap (following any redirects).
If the client has a username in the form of an email address, it MAY use the domain portion of this to attempt autodiscovery of the JMAP server.
To support clients that are unable to do SRV lookups, the server SHOULD make the hostname the same domain as the username if possible.
Authorization always starts with the client making a POST request to the authentication URL (found either via service autodiscovery or manual entry). The request MUST be of type application/json and specify an Accept: application/json header. The body of the request MUST be a single JSON object, encoded in UTF-8, with the following properties:
The server may use the client/device information to help identify the login to the user in a login log or other security reporting. Although hopefully unnecessary, they may also be helpful for working around client bugs in the future.
The server will respond with one of the following HTTP status codes:
The response body will be a single JSON object with the following properties.
This is the standard response to an initial request. Note, a server may return this even if the username is not actually active, to prevent enumeration. The client should then pick one of the methods from the list in the response to continue with authentication (if no methods supported by the client are in the list, it will not be able to get an access token).
An AuthMethod object MUST have a type property. This is a String representing the method of authentication. For some types, there may be other values required on the AuthMethod object in addition; see the description of types below. The following types are currently defined, but more may be added in the future. A client SHOULD offer the user the option to choose any of the method types returned that the client supports. The client MUST ignore any types it does not understand:
If not using "oauth", the user will at some point indicate to the client to continue authentication (after inputing any required token/code/password dependent on the auth method chosed). At this point the client submits a POST request to the same URL as before, with the body being a single JSON object with the following properties:
Note: The client SHOULD NOT store any password/code the user has entered beyond what is required to submit it to the server in this step.
The server will then return one of the same set of responses as before, which should be handled the same (for example, if two-factor authentication is required, a 200 response may be returned again and TOTP/U2F prompted for).
If the user chooses to authenticate using SMS, they may need to request the server to send the code to a particular number before they can submit a code. To do this, the client submits a POST request to the same URL as before, with the body being a single JSON object with the following properties:
The server SHOULD send the code to the given phone if the phone id is valid. If the code has already been sent, it is server-dependent whether it is sent again or ignored. The server MUST return one of the same set of responses as before, which should be handled the same (in most cases this will be a 200 response identical to before except that the isCodeSent property for the phone will now be true).
The response body will be a single JSON object with the following properties.
Future specifications will define their own properties on the capabilities object.
URLs are returned only after logging in. This allows different URLs to be used for users located in different geographic datacentres within the same service.
Note, if authentication is done via IP or mobile subscriber ID or some similar mechanism, a 201 response MAY be returned in response to the initial request (with just the username and client info).
The request is of the wrong content type, or does not contain data in the expected format. The client MUST NOT retry the same request. There is no content in the response.
Returned in response to a continuation request which failed (e.g. the password entered was not correct, or the out-of-band step was not completed successfully). The response body will be a single JSON object with the same properties as the 200 response, and the client may try again.
The JMAP authentication server is not available at this address. The client needs to rediscover the authentication URL. There is no content in the response.
The login attempt has failed permanently. This may be due to a password being incorrect, the login id expiring, or any other reason. The client MUST restart authentication (go back to sending the username and client info to the server). There is no content in the response.
Returned if the server is temporarily blocking this IP/client from authenticating. This may be due to too many failed password attempts, or detected username enumeration attempts, or any other reason. (Legitimate) clients should wait a while then try again. There is no content in the response.
Something has gone wrong internally, and the server is in a broken state. Don't automatically retry. There is no content in the response.
The server is currently down. Try again later with exponential backoff. There is no content in the response.
A server MAY (although SHOULD NOT) move end points for any services other than authentication at any time. If a request to the API/file upload/event source endpoint returns a 404, the client MUST refetch the URL endpoints. To do this, it should make an authenticated GET request to the authentication URL (see below for how to authenticate requests).
For OAuth logins, this is how the URLs may be fetched initially as well.
The server MUST respond with one of the following status codes:
The request was successful. The response will be of type application/json and consists of a single JSON object containing the following properties:
The Authorization header was missing or did not contain a valid token. Reauthenticate and then retry the request. There is no content in the response.
The JMAP server is no longer here. There is no content in the response.
Something has gone wrong internally, and the server is in a broken state. Don't automatically retry. There is no content in the response.
The server is currently down. Try again later with exponential backoff. There is no content in the response.
The validity of an access token is determined by the server. It may be valid for a limited time only, or expire after a certain time of inactivity, or be valid indefinitely etc. If an access token expires, it MUST NOT be resurrected. The client MUST restart the authentication process to get a new access token.
For OAuth, see the provider's documentation on revoking access tokens.
Otherwise, a client may revoke an access token at any time by making an authenticated DELETE HTTP request to the authentication URL (the one used to get the token in the first place). The response from the server will be one of the following:
The access token has now been revoked. There is no content in the response.
Failed due to missing Authorization header, or the Authorization header did not contain a valid access token. As per the HTTP spec, the response MUST have a WWW-Authenticate: Bearer header. There is no content in the response.
All HTTP requests other than to the authentication URL must be authenticated. To do this, the client MUST add an Authorization header to each request.
Once authenticated, the client will have an access token. This is used with the Bearer scheme as specified in [RFC6750] to authenticate HTTP requests.
For example, if user@example.com successfully logged in and the client received an accessToken of abcdef1234567890, to authenticate requests you would add the following header:
Authorization: Bearer abcdef1234567890
Sometimes, particularly in the browser context, authenticating a GET request using the usual Authorization header is not easily implemented. In such situations, a client may use a signed request instead. A signed request is an unauthenticated GET request containing a special query string parameter (a so-called token). The process below describes how a client can obtain such a token, then use it to download the file:
The server SHOULD expire any given signing token quickly for obvious security reasons, but the actual expiration policy is up to the server implementation.
Sample HTTP exchange demonstrating the use of a signed request to download a file:
POST /jmap/download/act1/blob2/mydocument.pdf HTTP/1.1 Host: server.example.com Authorization: Bearer abcdef1234567890 HTTP/1.1 200 OK Content-Type: text/plain Content-Length: 10 abcDEfGhIJ
GET /jmap/download/act1/blob2/mydocument.pdf?access_token=abcDEfGhIJ HTTP/1.1 Host: server.example.com HTTP/1.1 200 OK Content-Type: application/pdf Content-Length: 987654 << binary content >>
The client may make an API request to the server to get or set structured data. This request consists of an ordered series of method calls. These are processed by the server, which then returns an ordered series of responses.
To make an API request, the client makes an authenticated POST request to the API URL; see the Authentication section of the spec for how to discover this URL and how to authenticate requests.
The request MUST have a content type of application/json and be encoded in UTF-8.
The server SHOULD respond with one of the following HTTP response codes:
The API request was successful. The response will be of type application/json and consists of the response to the API calls, as described below.
The request was malformed. For example, it may have had the wrong content type, or have had a JSON object that did not conform to the API calling structure (see The structure of an API request below). The client SHOULD NOT retry the same request. There is no content in the response.
The Authorization header was missing or did not contain a valid token. Reauthenticate and then retry the request. As per the HTTP spec, the response MUST have a WWW-Authenticate header listing the available authentication schemes. There is no content in the response.
The API endpoint has moved. See the Authentication section of the spec for how to rediscover the current URL to use. There is no content in the response.
Returned if the client makes a request with more method calls than the server is willing to accept in a single request, or if the total bytes of the request is larger than the max size the server is willing to accept.
Returned if the client has made too many requests recently, or has too many concurrent requests currently in progress. Clients SHOULD wait a while then try again. The response MAY include a Retry-After header indicating how long to wait before making a new request.
Something has gone wrong internally, and the server is in a broken state. Don't automatically retry. There is no content in the response.
The server is currently down. Try again later with exponential backoff. There is no content in the response.
The client initiates an API request by sending the server a JSON array. Each element in this array is another array representing a method invocation on the server. The server will process the method calls and return a response consisting of an array in the same format. Each method call always contains three elements:
Example query:
[
["method1", {"arg1": "arg1data", "arg2": "arg2data"}, "#1"],
["method2", {"arg1": "arg1data"}, "#2"],
["method3", {}, "#3"]
]
The method calls MUST be processed sequentially, in order. Each API request (which, as shown, may contain multiple method calls) receives a JSON response in exactly the same format. The output of the methods MUST be added to the array in the same order as the methods are processed.
Example response:
[
["responseFromMethod1", {"arg1": 3, "arg2": "foo"}, "#1"],
["responseFromMethod2", {"isBlah": true}, "#2"],
["anotherResponseFromMethod2", {
"data": 10,
"yetmoredata": "Hello"
}, "#2"],
["aResponseFromMethod3", {}, "#3"]
]
If the data sent as an API request is not valid JSON or does not match the structure above, an error will be returned at the transport level. For example, when using JMAP over HTTP, a 400 Bad Request error will be returned at the HTTP level.
Possible errors for each method are specified in the method descriptions. If a method encounters an error, the appropriate error response MUST be inserted at the current point in the output array and, unless otherwise specified, further processing MUST NOT happen within that method call.
Any further method calls in the request MUST then be processed as normal.
An error response looks like this:
["error", {
type: "unknownMethod"
}, "client-id"]
The response name is error, and it has a type property as specified in the method description. Other properties may be present with further information; these are detailed in the method descriptions where appropriate.
Any method MAY return an error of type serverError if an unexpected or unknown error occurs during the processing of that call. The state of the server after such an error is undefined.
If an unknown method is called, an unknownMethod error (this is the type shown in the example above) MUST be inserted and then the next method call MUST be processed as normal.
If an unknown argument or invalid arguments (wrong type, or in violation of other specified constraints) are supplied to a method, an invalidArguments error MUST be inserted and then the next method call MUST be processed as normal.
Individual services will have custom features they wish to expose over JMAP. This may take the form of extra datatypes and/or methods not in the spec, or extra arguments to JMAP methods, or extra properties on existing data types (which may also appear in arguments to methods that take property names). To ensure compatibility with clients that don't know about a specific custom extension, and for compatibility with future versions of JMAP, the server MUST ONLY expose these extensions if the client explicitly opts in. Without opt-in, the server MUST follow the spec and reject anything that does not conform to it as specified.
As always, the server must be strict about data received from the client. Arguments need to be checked for validity; a malicious user could attempt to find an exploit through the API. In case of invalid arguments (unknown/insufficient/wrong type for data etc.) the method MUST return an invalidArguments error and terminate.
To ensure the client always sees a consistent view of the data, the state accessed by a method call MUST NOT change during the execution of the method, except due to actions by the method call itself. The state MAY change in-between method calls (even within a single API request).
The JSON datatypes are limited to those found in JavaScript. A Number in JavaScript is represented as a signed double (64-bit floating point). However, except where explicitly specified, all numbers used in this API are unsigned integers <= 2^53 (the maximum integer that may be reliably stored in a double). This implicitly limits the maximum length of message lists in queries and the like.
Where a JMAP API specifies Date as a type, it means a string in [RFC3339] date-time format, with the time-offset component always Z (i.e. the date-time MUST be in UTC time) and time-secfrac always omitted. The "T" and "Z" MUST always be upper-case. For example, "2014-10-30T14:12:00Z".
Unless otherwise specified, a missing property in the arguments object of a request (from the client), or a response (from the server) MUST be intepreted exactly the same as that property having the value null.
Unless otherwise specified, a missing property in a data object MUST be interpreted in the following ways: - In the response to a getFoos style call, or when creating an object in a setFoos style call, a missing property MUST be interpreted as though it had the default value for that type, or null if no default is specified. - When updating an object in a setFoos style call, a missing property MUST be interpreted as the existing value for that property (i.e. don't update it).
For network efficiency, when fetching the server and client may make use of the above and omit properties which have the default value for the data type.
JMAP provides a uniform interface for creating, retrieving, updating and deleting various types of objects. For a Foo data type, records of that type would be fetched via a getFoos call and modified via a setFoos call. Delta updates may be fetched via a getFooUpdates call. These methods all follow a standard format as described below.
Objects of type Foo are fetched via a call to getFoos. Methods with a name starting with get MUST NOT alter state on the server.
This method may take some or all of the following arguments; see the definition of the data type in question. However, if one of the following arguments is available, it will behave exactly as specified below.
The response to getFoos is called foos. It has the following arguments:
The following error may be returned instead of the foos response:
accountNotFound: Returned if an accountId was explicitly included with the request, but it does not correspond to a valid account.
accountNotSupportedByMethod: Returned if the accountId given corresponds to a valid account, but the account does not support this data type.
requestTooLarge: Returned if the number of ids requested by the client exceeds the maximum number the server is willing to process in a single method call.
invalidArguments: Returned if one of the arguments is of the wrong type, or otherwise invalid. A description property MAY be present on the response object to help debug with an explanation of what the problem was.
When the state of the set of Foo records changes on the server (whether due to creation, updates or deletion), the state property of the foos response will change. The getFooUpdates call allows a client to efficiently update the state of any its Foo cache to match the new state on the server. It takes the following arguments:
The response to getFooUpdates is called fooUpdates. It has the following arguments:
The maxChanges argument (and hasMoreUpdates response argument) is available for data types with potentially large amounts of data (i.e. those for which there is a getFooList method available for loading the data in pages). If a maxChanges is supplied, or set automatically by the server, the server must try to limit the number of ids across changed and removed to the number given. If there are more changes than this between the client's state and the current server state, the update returned MUST take the client to an intermediate state, from which the client can continue to call getFooUpdates until it is fully up to date. The server MUST NOT return more ids than the maxChanges total. If the server is unable to calculate a suitable intermediate state, it MUST return a cannotCalculateChanges error.
If a Foo record has been modified AND deleted since the oldState, the server SHOULD just return the id in the removed response, but MAY return it in the changed response as well. If a Foo record has been created AND deleted since the oldState, the server SHOULD remove the Foo id from the response entirely, but MAY include it in the removed response.
The following errors may be returned instead of the fooUpdates response:
accountNotFound: Returned if an accountId was explicitly included with the request, but it does not correspond to a valid account.
accountNotSupportedByMethod: Returned if the accountId given corresponds to a valid account, but the account does not support this data type.
invalidArguments: Returned if the request does not include one of the required arguments, or one of the arguments is of the wrong type, or otherwise invalid. A description property MAY be present on the response object to help debug with an explanation of what the problem was.
cannotCalculateChanges: Returned if the server cannot calculate the changes from the state string given by the client. Usually due to the client's state being too old, or the server being unable to produce an update to an intermediate state when there are too many updates. The client MUST invalidate its Foo cache.
Modifying the state of Foo objects on the server is done via the setFoos method. This encompasses creating, updating and destroying Foo records. This has two benefits:
The setFoos method takes the following arguments:
Each create, update or destroy is considered an atomic unit. It is permissible for the server to commit some of the changes but not others, however it is not permissible to only commit part of an update to a single record (e.g. update a name property but not a count property, if both are supplied in the update object).
If a create, update or destroy is rejected, the appropriate error MUST be added to the notCreated/notUpdated/notDestroyed property of the response and the server MUST continue to the next create/update/destroy. It does not terminate the method.
If an id given cannot be found, the update or destroy MUST be rejected with a notFound set error.
Some record objects may hold references to others (foreign keys). When records are created or modified, they may reference other records being created in the same API request by using the creation id prefixed with a #. The order of the method calls in the request by the client MUST be such that the record being referenced is created in the same or an earlier call. The server thus never has to look ahead. Instead, while processing a request (a series of method calls), the server MUST keep a simple map for the duration of the request of creation id to record id for each newly created record, so it can substitute in the correct value if necessary in later method calls. Creation ids sent by the client SHOULD be unique within the single API request for a particular data type. If a creation id is reused, the server MUST map the creation id to the most recently created item with that id.
The response to setFoos is called foosSet. It has the following arguments:
A SetError object has the following properties:
Other properties may also be present on the object, as described in the relevant methods.
The following errors may be returned instead of the foosSet response:
accountNotFound: Returned if an accountId was explicitly included with the request, but it does not correspond to a valid account.
accountNotSupportedByMethod: Returned if the accountId given corresponds to a valid account, but the account does not support this data type.
accountReadOnly: Returned if the account has isReadOnly == true.
requestTooLarge: Returned if the total number of objects to create, update or destroy exceeds the maximum number the server is willing to process in a single method call.
invalidArguments: Returned if one of the arguments is of the wrong type, or otherwise invalid. A description property MAY be present on the response object to help debug with an explanation of what the problem was.
stateMismatch: Returned if an ifInState argument was supplied and it does not match the current state.
Binary data is referenced by a blobId in JMAP. A blob id does not have a name inherent to it, but this is normally given in the same object that contains the blob id.
After completing authentication, the client will receive a downloadUrl as part of the response. This is in [RFC6570] URI Template (level 1) format. The URL MUST contain variables called accountId and blobId. The URL SHOULD contain a variable called name.
The client may use this template in combination with an accountId and blobId to download any binary data (files) referenced by other objects. Since a blob is not associated with a particular name, the template SHOULD allow a name to be substituted in as well; the server will return this as the filename if it sets a Content-Disposition header.
To download the data the client MUST make an authenticated GET request to the download URL with the appropriate variables substituted in, and then follow any redirects. In situations where it's not easy to authenticate the download request (e.g.: when downloading a file through a link in a HTML document), the client MAY use a signed GET request (see below for how to issue a signed request).
After following redirects, the server MUST return one of the following responses to a request to the download URL:
Request successful. The binary data is returned. The Content-Type header SHOULD be set to the correct content type for the content.
The Authorization header was missing or did not contain a valid token and there was no access_token query parameter, or it did not contain a valid token. Reauthenticate and then retry the request. As per the HTTP spec, the response MUST have a WWW-Authenticate header listing the available authentication schemes.
The server MAY return an HTML page response, which clients MAY show to the user. This is primarily for when the URL is passed off to the browser, and the JMAP client may not see the actual response.
The file was not found at this address.
The server is currently down. The client should try again later with exponential backoff. There is no content in the response.
There is a single endpoint which handles all file uploads, regardless of what they are to be used for. To upload a file, the client submits a POST request to the file upload endpoint (see the authentication section for information on how to obtain this URL). The Content-Type MUST be correctly set for the type of the file being uploaded. The request MUST be authenticated as per any HTTP request. The request MAY include an X-JMAP-AccountId header, with the value being the account to use for the request. Otherwise, the default account will be used.
The server will respond with one of the following HTTP response codes:
The content of the response is a single JSON object with the following properties:
Once the file has been used, for example attached to a draft message, the file will no longer expire, and is instead guaranteed to exist while at least one other object references it. Once no other object references it, the server MAY immediately delete the file at any time. It MUST NOT delete the file during the method call which removed the last reference, so that if there is a create and a delete within the same call that both reference the file, this always works.
If uploading a file would take the user over quota, the server SHOULD delete previously uploaded (but unused) files before their expiry time. This means a client does not have to explicitly delete unused temporary files (indeed, there is no way for it to do so).
If identical binary content is uploaded, the same blobId SHOULD be returned.
The server MUST return one of the following responses to a request to the upload URL:
The request was malformed (this includes the case where an X-JMAP-AccountId header is sent with a value that does not exist). The client SHOULD NOT retry the same request. There is no content in the response.
The Authorization header was missing or did not contain a valid token. Reauthenticate and then retry the request. As per the HTTP spec, the response MUST have a WWW-Authenticate header listing the available authentication schemes. There is no content in the response.
The upload endpoint has moved. See the Authentication section of the spec for how to rediscover the current URL to use. There is no content in the response.
The file is larger than the maximum size the server is willing to accept for a single file. The client SHOULD NOT retry uploading the same file. There is no content in the response. The client may discover the maximum size the server is prepared to accept by inspecting the server capabilities object, returned with the successful authentication response.
The server MAY choose to not allow certain content types to be uploaded, such as executable files. This error response is returned if an unacceptable type is uploaded. The client SHOULD NOT retry uploading the same file. There is no content in the response.
Returned if the client has made too many upload requests recently, or has too many concurrent uploads currently in progress. Clients SHOULD wait a while then try again. The response MAY include a Retry-After header indicating how long to wait before making a new request.
The server is currently down. The client should try again later with exponential backoff. There is no content in the response.
Any modern email client should be able to update instantly whenever the data on the server is changed by another client or message delivery. Push notifications in JMAP occur out-of-band (i.e. not over the same connection as API exchanges) so that they can make use of efficient native push mechanisms on different platforms.
The general model for push is simple and does not send any sensitive data over the push channel, making it suitable for use with less trusted 3rd party intermediaries. The format allows multiple changes to be coalesced into a single push update, and the frequency of pushes to be rate limited by the server. It doesn't matter if some push events are dropped before they reach the client; it will still get all changes next time it syncs.
When something changes on the server, the server pushes a small JSON object to the client with the following property:
A ChangedStates object is a map of the type name (e.g. "Mailbox" or "Message") to the current state token for that type (i.e. the "state" property that would currently be returned by a call to "getMailboxes" or "getMessages", as appropriate). The types in JMAP are "Mailbox", "Thread", "Message", "ContactGroup", "Contact", "Calendar", "CalendarEvent".
Upon receiving this data, the client can compare the new state strings with its current values to see whether it has the current data for these types. The actual changes can then be efficiently fetched in a single standard API request (using the getFooUpdates type methods).
There are two mechanisms by which the client can receive the push events. The first is directly via a text/event-stream resource, as described in <http://www.w3.org/TR/eventsource/>. This is essentially a long running HTTP request down which the server can push data. When a change occurs, the server MUST push an event called state to any connected clients.
The server MAY also set a new Last-Event-Id that encodes the entire server state visible to the user. When a new connection is made to the event-source endpoint, the server can then work out whether the client has missed some changes which it should send immediately.
The server MUST also send an event called ping with an empty object as the data if a maximum of 5 minutes has elapsed since the previous event. This MUST NOT set a new Last-Event-Id. A client may detect the absence of these to determine that the HTTP connection has been dropped somewhere along the route and so it needs to re-establish the connection.
Refer to the Authentication section of this spec for details on how to get the URL for the event-source endpoint. The request must be authenticated using an Authorization header like any HTTP request.
A client MAY hold open multiple connections to the event-source, although it SHOULD try to use a single connection for efficiency.
The second push mechanism is to register a callback URL to which the JMAP server will make an HTTPS POST request whenever the event occurs. The request MUST have a content type of application/json and contain the same UTF-8 JSON encoded object as described above as the body.
The JMAP server MUST also set the following headers in the POST request: - X-JMAP-EventType: state - X-JMAP-User: ${username} where ${username} is the username of the authenticated user for which the push event occurred.
The JMAP server MUST follow any redirects. If the final response code from the server is 2xx, the callback is considered a success. If the response code is 503 (Service Unavailable), the JMAP server MAY try again later (but may also just drop the event). If the response code is 429 (Too Many Requests) the JMAP server SHOULD attempt to reduce the frequency of pushes to that URL. Any other response code MUST be considered a permanent failure and the callback should be deregistered (not tried again even for future events unless explicitly re-registered by the client).
The URL set by the client MUST use the HTTPS protocol and SHOULD encode within it a unique token that can be verified by the server to know that the request comes from the JMAP server the authenticated client connected to.
The callback is tied to the access token used to create it. Should the access token expire or be revoked, the callback MUST be removed by the JMAP server. The client MUST re-register the callback after reauthenticating to resume callbacks.
Each session may only have a single callback URL registered. It can be set or retrieved using the following API calls.
To set the web hook, make a call to setPushCallback. It takes the following argument:
The response to setPushCallback is called pushCallbackSet. It has the following argument:
The following error may be returned instead of the mailboxesSet response:
invalidUrl: Returned if the URL does not begin with https://, or is otherwise syntactically invalid or does not resolve.
To check the currently set callback URL (if any), make a call to getPushCallback. It does not take any arguments. The response to getPushCallback is called pushCallback. It has a single argument: