| JMAP | N. Jenkins |
| Internet-Draft | FastMail |
| Intended status: Standards Track | November 29, 2017 |
| Expires: June 2, 2018 |
JSON Meta Application Protocol
draft-ietf-jmap-core-03
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 https://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 June 2, 2018.
Copyright (c) 2017 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 (https://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 data 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]. Unless otherwise noted, all the property names and values are case sensitive.
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:
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).
Where Date is given as a type, it means a string in [RFC3339] date-time format. To ensure a normalised form, the time-secfrac MUST always be omitted and any letters in the string (e.g. "T" and "Z") MUST be upper-case. For example, "2014-10-30T14:12:00+08:00".
Where UTCDate is given as a type, it means a Date where the time-offset component MUST be Z (i.e. it must be in UTC time). For example, "2014-10-30T06:12:00Z".
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 ([RFC3629]).
A user represents a set of permissions relating to what data can be seen.
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).
JMAP uses HTTP [RFC7230] to expose API, Push, Upload and Download resources. Implementations MUST support HTTP/1.1, and MAY support later versions. Support for common HTTP mechanisms such as redirection and caching are assumed.
All HTTP requests MUST be authenticated. Servers MUST conform with the [RFC7235] HTTP Authentication framework to reject requests that fail authentication and inform the client of available authentication schemes.
Clients SHOULD understand and be able to handle standard HTTP status codes appropriately.
An authenticated client can fetch the JMAP session object with details about the data and capabilities the server can provide as shown in section 2. The client may then exchange data with the server using four different mechanisms:
To communicate with a JMAP server you need two things to start:
An authenticated GET request to the JMAP session resource MUST return the details about the data and capabilities the server can provide to the client given those credentials.
The response to a successful request is a JSON object with the following properties:
Future specifications will define their own properties on the capabilities object. Servers MAY advertise vendor-specific JMAP extensions. To avoid conflict, the identifiers for these MUST be a URI beginning with a domain owned by the vendor. Clients MUST opt in to any specifications it wishes to use (see "Making an API request").
To ensure future compatibility, other properties MAY be included on the JMAP session object. Clients MUST ignore any properties they are not expecting.
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 JMAP Session resource 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.
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 resource, the location of which may be found on the JMAP session object.
The request MUST consist of a single Request object, encoded in UTF-8. If successful, the response MUST be of type application/json and consist of a single Response object.
A Request object has the following properties:
Future specifications MAY add further properties to the Request object to extend the semantics. To ensure forwards compatability, a server MUST ignore any other properties it does not understand on the JMAP request object.
{
"using": [ "ietf.org/rfc/jmap-core", "ietf.org/rfc/jmap-mail" ],
"methodCalls": [
["method1", {"arg1": "arg1data", "arg2": "arg2data"}, "#1"],
["method2", {"arg1": "arg1data"}, "#2"],
["method3", {}, "#3"]
]
}
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).
The server can advertise custom extensions it supports by including the identifiers in the capabilities object. Identifiers for vendor extensions MUST be a URL belonging to a domain owned by the vendor, to avoid conflict. The URL SHOULD resolve to documentation for the changes the extension makes.
To ensure compatibility with clients that don't know about a specific custom extension, and for compatibility with future versions of JMAP, to use an extension the client MUST opt in by passing the appropriate capability identifier in the using array of the Request object. The server MUST only follow the specifications that are opted-into and behave as though it does not implement anything else when processing a request.
A Response object has the following properties:
{
"methodResponses": [
["responseFromMethod1", {"arg1": 3, "arg2": "foo"}, "#1"],
["responseFromMethod2", {"isBlah": true}, "#2"],
["anotherResponseFromMethod2", {
"data": 10,
"yetmoredata": "Hello"
}, "#2"],
["aResponseFromMethod3", {}, "#3"]
]
}
An argument to a method may be specified to have a default value. If omitted by the client, the server MUST treat the method call the same as if the default value had been specified. Similarly, the server MAY omit any argument in a response which has the default value.
Unless otherwise specified in a method description, null is the default value for any argument in a request or response where this is allowed by the type signature. Other arguments may only be omitted if an explicit default value is defined in the method description.
If the data sent as an API request is not valid JSON or does not match the structure above, 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 methodResponses 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, missing and not optional, 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.
To allow clients to make more efficient use of the network and avoid round trips, an argument to one method can be taken from the result of a previous method call.
To do this, the client prefixes the argument name with "#". The value is a ResultReference object as described below. When processing a method call, the server MUST first check the arguments object for any names beginning with "#". If found, the back reference should be resolved and the value used as the "real" argument. The method is then processed as normal. If any back reference fails to resolve, the whole method MUST be rejected with a resultReference error. If an argument object contains the same argument name in normal and referenced form (e.g. foo and #foo), the method MUST return an invalidArguments error.
A ResultReference object has the following properties:
To resolve:
If the currently referenced value is a JSON array, the reference token may be exactly the single character *, making the new referenced value the result of applying the rest of the JSON pointer tokens to every item in the array and returning the results in the same order in a new array. If the result of applying the rest of the pointer tokens to a value was itself an array, its items should be included individually in the output rather than including the array itself (i.e. the result is flattened from an array of arrays to a single array).
As a simple example, suppose we have the following API request methodCalls:
[[ "getFooUpdates", {
"sinceState": "abcdef"
}, "t0" ],
[ "getFoos", {
"#ids": {
"resultOf": "t0",
"path": "/changed"
}
}, "t1" ]]
After executing the first method call the methodResponses array is:
[[ "fooUpdates", {
"accountId": "1",
"oldState": "abcdef",
"newState": "123456",
"hasMoreUpdates": false,
"changed": [ "f1", "f4" ],
"removed": []
}, "t0" ]]
So to execute the getFoos call, we look through the arguments and find there is one with a # prefix. To resolve this, we apply the algorithm above:
The JMAP server now continues to process the getFoos call as though the arguments were:
{
"ids": [ "msg1", "msg4" ]
}
Now a more complicated example using the JMAP Mail data model: fetch the "from"/"date"/"subject" for every message in the first 10 threads in the Inbox (sorted newest first):
[[ "getMessageList", {
"filter": { inMailbox: "id_of_inbox" },
"sort": [ "date desc" ],
"collapseThreads": true,
"position": 0,
"limit": 10
}, "t0" ],
[ "getMessages", {
"#ids": {
"resultOf": "t0",
"path": "/ids"
},
"properties": [ "threadId" ]
}, "t1" ],
[ "getThreads", {
"#ids": {
"resultOf": "t1",
"path": "/list/*/threadId"
}
}, "t2" ],
[ "getMessages", {
"#ids": {
"resultOf": "t2"
"path": "/list/*/messageIds"
},
"properties": [ "from", "date", "subject" ]
}, "t3" ]]
After executing the first 3 method calls the methodResponses array might be:
[[ "messageList", {
"accountId": "1",
"filter": { inMailbox: "id_of_inbox" },
"sort": [ "date desc" ],
"collapseThreads": true,
"state": "abcdefg",
"canCalculateUpdates": true,
"position": 0,
"total": 101,
"ids": [ "msg1023", "msg223", "msg110", "msg93", "msg91", "msg38", "msg36", "msg33", "msg11", "msg1" ]
}, "t0" ],
[ "messages", {
"accountId": "1",
"state": "123456",
"list": [{
"id": "msg1023",
"threadId": "trd194",
}, {
"id": "msg223",
"threadId": "trd114"
},
... etc...
],
"notFound": null
}, "t1" ],
[ "threads", {
"accountId": "1",
"state": "123456",
"list": [{
"id: "trd194",
"messageIds": [ "msg1020", "msg1021", "msg1023" ]
}, {
"id: "trd114",
"messageIds": [ "msg201", "msg223" ]
},
... etc...
],
"notFound": null
}, "t2" ]]
So to execute the final getMessages call, we look through the arguments and find there is one with a # prefix. To resolve this, we apply the algorithm:
The JMAP server now continues to process the getMessages call as though the arguments were:
{
"ids": [ "msg1020", "msg1021", "msg1023", "msg201", "msg223", etc... ],
"properties": [ "from", "date", "subject" ]
}
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.
Each individual method call within a request MUST be serializable; concurrent execution of methods MUST produce the same effect as running them one at a time in some order.
This means that the observable ordering may interleave method calls from different concurrent API requests, such that the data on the server may change between two method calls within a single API request.
JMAP provides a uniform interface for creating, retrieving, updating and deleting objects of a particular type. 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.
Methods with a name starting with get MUST NOT alter state on the server.
Objects of type Foo are fetched via a call to getFoos.
It takes the following arguments:
The response to getFoos is called foos. It has the following arguments:
The following error may be returned instead of the foos response:
accountNotFound: An accountId was explicitly included with the request, but it does not correspond to a valid account.
accountNotSupportedByMethod: The accountId given corresponds to a valid account, but the account does not support this data type.
requestTooLarge: The number of ids requested by the client exceeds the maximum number the server is willing to process in a single method call.
invalidArguments: 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 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:
If a maxChanges is supplied, or set automatically by the server, the server MUST ensure the number of ids returned across changed and removed does not exceed this limit. If there are more changes than this between the client's state and the current server state, the update returned SHOULD generate an update to take the client to an intermediate state, from which the client can continue to call getMessageUpdates until it is fully up to date. If it is unable to calculate an intermediate state, it MUST return a cannotCalculateChanges error response instead.
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 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: An accountId was explicitly included with the request, but it does not correspond to a valid account.
accountNotSupportedByMethod: The accountId given corresponds to a valid account, but the account does not support this data type.
invalidArguments: 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: 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.
Maintaining state to allow calculation of getFooUpdates can be expensive for the server, but always returning cannotCalculateChanges severely increases network traffic and resource usage for the client. To allow efficient sync, servers SHOULD be able to calculate changes from any state string that was given to a client within the last 30 days (but of course may support calculating updates from states older than this).
Modifying the state of Foo objects on the server is done via the setFoos method. This encompasses creating, updating and destroying Foo records. This allows the server to sort out ordering and dependencies that may exist if doing multiple operations at once (for example to ensure there is always a minimum number of a certain record type).
The setFoos method takes the following arguments:
The value associated with each pointer determines how to apply that patch:
Any server-set properties MAY be included in the patch if their value is identical to the current server value (before applying the patches to the object). Otherwise, the update MUST be rejected with an
invalidProperties SetError. This patch definition is designed such that an entire Foo object is also a valid PatchObject. The client MAY choose to optimise network usage by just sending the diff, or MAY just send the whole object; the server processes it the same either way.
Each creation, modification or destruction of an object is considered an atomic unit. It is permissible for the server to commit changes to some objects 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).
The final state MUST be valid after the setFoos is finished, however the server may have to transition through invalid intermediate states (not exposed to the client) while processing the individual create/update/destroy requests. For example, suppose there is a "name" property that must be unique. A single method call could rename an object A => B, and simultaneously rename another object B => A. The final state is valid, so this is allowed, however if processed sequentially there will be an internal state where temporarily both objects have the same name.
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 are scoped by type; a separate creation id -> id map MUST be kept for each type for the duration of the request. Foreign key references are always for a particular record type, so use of the same creation key in two different types cannot cause any ambiguity. 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 for the same type, 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:
The following SetError types are defined and may be returned for set operations on any record type:
The SetError object SHOULD also have a property called
properties of type String[] that lists all the properties that were invalid. Individual methods MAY specify more specific errors for certain conditions that would otherwise result in an invalidProperties error. If the condition of one of these is met, it MUST be returned instead of the invalidProperties error.
Other possible SetError types MAY be given in specific method descriptions. Other properties MAY also be present on the SetError object, as described in the relevant methods.
The following errors may be returned instead of the foosSet response:
accountNotFound: An accountId was explicitly included with the request, but it does not correspond to a valid account.
accountNotSupportedByMethod: The accountId given corresponds to a valid account, but the account does not support this data type.
accountReadOnly: The account has isReadOnly == true.
requestTooLarge: 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: 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: An ifInState argument was supplied and it does not match the current state.
Suppose we have a type Todo with the following properties:
Now we fetched a Todo of id "a" (let's presume we already knew a Todo with this id existed):
[["getTodos", {
"ids": ["a"]
}, "0"]]
and got back
[["todos", {
"accountId": "x",
"state": "10324",
"list": [{
"id": "a",
"title": "Practice Piano",
"keywords": {
"beethoven": true,
"mozart": true,
"liszt": true,
"rachmaninov": true
},
"neuralNetworkTimeEstimation": 3600
}]
}, "0"]]
Now the user adds a keyword "chopin" and removes the keyword "mozart". The client may send the whole object to the server, as this is a valid PatchObject:
[["setTodos", {
"ifInState": "10324",
"update": {
"a": {
"id": "a",
"title": "Practice Piano",
"keywords": {
"beethoven": true,
"chopin": true,
"liszt": true,
"rachmaninov": true,
}
"neuralNetworkTimeEstimation": 360
}
}
}, "0"]]
or it may send a minimal patch:
[["setTodos", {
"ifInState": "10324",
"update": {
"a": {
"keywords/chopin": true,
"keywords/mozart": null
}
}
}, "0"]]
The effect is exactly the same on the server in either case, and presuming the server is still in state "10324" it will probably return success:
[["todosSet", {
"accountId": "x",
"oldState": "10324",
"newState": "10329",
"updated": {
"a": {
"neuralNetworkTimeEstimation": 5400
}
}
}, "0"]]
The server changed the "neuralNetworkTimeEstimation" property on the object as part of this change; as this changed in a way not explicitly requested by the PatchObject sent to the server, it is returned with the "updated" confirmation.
For data sets where the total amount of data is expected to be very small, clients can just fetch the complete set of data and then do any sorting/filtering locally. However, for large data sets (e.g. multi-gigabyte mailboxes), the client needs to be able to perform a query on the server for the data type.
A query on the set of Foos in an account is made by calling getFooList. This takes a number of arguments to determine which records to include, how they should be sorted, and which part of the result should be returned (the full list may be very long). The result is returned as a list of Foo ids.
A call to getFooList takes the following arguments:
If an anchor argument is given, then after filtering and sorting the anchor is searched for in the results list. If found, the anchor offset is then subtracted from this index. If the resulting index is now negative, it is clamped to 0. This index is now used exactly as though it were supplied as the position argument. If the anchor is not found, the call is rejected with an anchorNotFound error.
If an anchor is specified, any position argument supplied by the client MUST be ignored. If anchorOffset is null, it defaults to 0. If no anchor is supplied, any anchor offset argument MUST be ignored.
A client can use anchor instead of position to find the index of an id within a large set of results.
The response to a call to getFooList is called fooList. It has the following arguments:
The following errors may be returned instead of the fooList response:
accountNotFound: An accountId was explicitly included with the request, but it does not correspond to a valid account.
accountNotSupportedByMethod: The accountId given corresponds to a valid account, but the account does not support this data type.
anchorNotFound: An anchor argument was supplied, but it cannot be found in the Foo list.
unsupportedSort: The sort is syntactically valid, but includes a property the server does not support sorting on.
unsupportedFilter: The filter is syntactically valid, but the server cannot process it.
invalidArguments: 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.
The getFooListUpdates call allows a client to efficiently update the state of any cached foo list to match the new state on the server. It takes the following arguments:
The response to getFooListUpdates is called fooListUpdates It has the following arguments:
The result of this should be that if the client has a cached sparse array of foo ids in the list in the old state:
fooIds = [ "id1", "id2", null, null, "id3", "id4", null, null, null ]
then if it splices out all foos in the removed array:
removed = [ "id2", … ]; fooIds => [ "id1", null, null, "id3", "id4", null, null, null ]
and splices in (in order) all of the foos in the added array:
added = [{ fooId: "id5", index: 0, … }];
fooIds => [ "id5", "id1", null, null, "id3", "id4", null, null, null ]
and truncates or extends to the new total length, then the foo list will now be in the new state.
The following errors may be returned instead of the fooListUpdates response:
accountNotFound: An accountId was explicitly included with the request, but it does not correspond to a valid account.
accountNotSupportedByMethod: The accountId given corresponds to a valid account, but the account does not support this data type.
invalidArguments: 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.
tooManyChanges: There are more changes the the client's maxChanges argument. Each item in the removed or added array is considered as one change. The client may retry with a higher max changes or invalidate its cache of the foo list.
cannotCalculateChanges: The server cannot calculate the changes from the state string given by the client. Usually due to the client's state being too old. The client MUST invalidate its cache of the foo list.
Binary data is referenced by a blobId in JMAP, and uploaded/downloaded separately to the core API. A blobId does not have a name inherent to it, but this is normally given in the same object that contains the blobId. The data represented by a blobId is immutable.
Any blobId that exists within an account may be used when creating/updating another object in that account. For example, an Email type may have a blobId that represents the RFC5322 representation of the message. A client could create a new Email object with an attachment and use this blobId, in effect attaching the old message to the new one. Similarly it could attach any existing existing attachment of an old message without having to download and upload it again.
When the client uses a blobId in a create/update, the server MAY assign a new blobId to refer to the same binary data from the new/updated object. If it does so, it MUST return any properties that contain a changed blobId in the created/updated response so the client gets the new ids.
A blob that is not referenced by a JMAP object (e.g. as a message attachment), MAY be deleted by the server to free up resources. Uploads (see below) are initially unreferenced blobs. To ensure interoperability:
There is a single endpoint which handles all file uploads for an account, regardless of what they are to be used for. The JMAP session object has an uploadUrl property in [RFC6570] URI Template (level 1) format, which MAY contain a variable called accountId. The client may use this template in combination with an accountId (if required in the template) to get the URL of the file upload resource.
To upload a file, the client submits an authenticated POST request to the file upload resource.
A successful request MUST return a single JSON object with the following properties as the response:
If identical binary content to an existing blob in the account is uploaded, the existing blobId MAY be returned.
The JMAP session object has a downloadUrl property, which is in [RFC6570] URI Template (level 1) format. The URL MUST contain a variable called blobId, MAY contain a variable called accountId, and SHOULD contain a variable called name.
The client may use this template in combination with an accountId (if required in the URL template) 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 makes an authenticated GET request to the download URL with the appropriate variables substituted in. The client SHOULD send an Accept header with the content type they would like the server to return for the file. The Content-Type header of a successful response SHOULD be set to the type as requested in the Accept header by the client, or application/octet-stream if unknown and no Accept header given.
Push notifications allow clients to efficiently update (almost) instantly to stay in sync with data changes on the server. In JMAP, push notifications 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 sends minimal data over the push channel. 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 StateChange object to the client. A StateChange object has the following properties:
Future specifications may define further values. Clients MUST treat an unrecognised value the same as
unknown. Clients in battery constrained environments may use this information to decide whether to immediately fetch the changes.
A push subscription is a message delivery context established between the client and a push service. A PushSubscription object has the following properties:
Clients may register the push subscription with the JMAP server, which will then make a POST request to the associated push endpoint whenever an event occurs.
The POST request MUST have a content type of application/json and contain the utf-8 JSON encoded StateChange object as the body. The request MUST have a TTL header, and MAY have Urgency and/or Topic headers, as specified in section 5 of [RFC8030].
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 4xx or 5xx response code MUST be considered a permanent failure and the push subscription should be deregistered (not tried again even for future events unless explicitly re-registered by the client).
The use of this push endpoint conforms with the use of a push endpoint by an Application Server as defined in [RFC8030]. A client MAY use the rest of [RFC8030] in combination with its own Push Server to form a complete end-to-end solution, or MAY rely on alternative mechanisms to ensure the delivery of the pushed data after it leaves the JMAP server.
Each session may only have a single push subscription registered. The push subscription is tied to the access token used to create it. Should the access token expire or be revoked, the push subscription MUST be removed by the JMAP server. The client MUST re-register the push subscription after reauthenticating to resume callbacks.
To set the push subscription, make a call to setPushSubscription. It takes the following argument:
The response to setPushSubscription is called pushSubscriptionSet. It has no arguments.
The following errors may be returned instead of the pushSubscriptionSet response:
invalidUrl: Returned if the URL does not begin with https://, or is otherwise syntactically invalid or does not resolve.
forbidden: Returned if the URL is valid, but for policy reasons the server is not willing to connect to it.
To check the currently set push subscription (if any), make a call to getPushSubscription. It does not take any arguments. The response is called pushSubscription and it has a single argument:
Clients that can hold open TCP connections can connect directly to the JMAP server to receive push notifications via a text/event-stream resource, as described in <http://www.w3.org/TR/eventsource/>. This is a long running HTTP request down which the server can push data.
When a change occurs in the data on the server, it pushes an event called state to any connected clients, with the StateChange object as the data.
The server SHOULD also send a new event id that encodes the entire server state visible to the user immediately after sending a state event. When a new connection is made to the event-source endpoint, a client following the server-sent events specification will send a Last-Event-ID HTTP header with the last id it saw, which the server can use to work out whether the client has missed some changes. If so, it SHOULD send these changes immediately on connection.
The client MAY add a query parameter called closeafter with value state to the event-source resource URL when requesting the event-source resource. If set, the server MUST end the HTTP response after pushing a state event. This can be used by clients in environments where buffering proxies prevent the pushed data from arriving immediately, or indeed at all, when operating in the usual mode.
The client MAY add a query parameter called ping, with a positive integer value representing a length of time in seconds, e.g. ping=300. If set, the server MUST send an event called ping whenever this time elapses since the previous event was sent. This MUST NOT set a new event id.
The server MAY modify the interval given as a query parameter to be subject to a minimum and/or maximum value. For interoperability, servers MUST NOT have a minimum allowed value higher than 30 or a maximum allowed value less than 300.
The data for the ping event MUST be a JSON object containing an interval property, the value (type Number) being the interval in seconds the server is using to send pings (this may be different to the requested value if the server clamped it to be within a min/max value).
Clients can monitor for the ping event to help determine when the closeafter mode may be required.
Refer to the Authentication section of this spec for details on how to get the URL for the event-source resource. Requests to the resource MUST be authenticated.
A client MAY hold open multiple connections to the event-source resource, although it SHOULD try to use a single connection for efficiency.
All HTTP requests MUST use [RFC5246] TLS (https) transport to ensure the confidentiality of data sent and received via JMAP. Clients MUST validate TLS certificate chains to protect against man-in-the-middle attacks.
A number of HTTP authentication schemes have been standardised (<https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml>). Servers should take care to assess the security characteristics of different schemes in relation to their needs when deciding what to implement.
If offering the Basic authentication scheme, services are strongly recommended to not allow a user's regular password but require generation of a unique "app password" via some external mechanism for each client they wish to connect. This allows connections from different devices to be differentiated by the server, and access to be individually revoked.
Unless secured by something like DNSSEC, autodiscovery of server details is vulnerable to a DNS poisoning attack leading to the client talking to an attacker's server instead of the real JMAP server. The attacker may then man-in-the-middle requests and depending on the authentication scheme, steal credentials to generate its own requests.
The security considerations of [RFC7159] apply to the use of JSON as the data interchange format.
A small request may result in a very large response, and require considerable work on the server if resource limits are not enforced. JMAP provides mechanisms for advertising and enforcing a wide variety of limits for mitigating this threat, including limits on number of objects fetched in a single method call, number of methods in a single request, number of concurrent requests, etc.
JMAP servers MUST implement sensible limits to mitigate against resource exhaustion attacks.
When data changes, a small object is pushed with the new state strings for the types that have changed. While the data here is minimal, a passive man-in-the-middle attacker may be able to gain useful information. To ensure confidentiality, if the push is sent via a third party outside of the control of the client and JMAP server the client MUST specify encryption keys when establishing the PushSubscription.
The privacy and security considerations of [RFC8030] and <https://tools.ietf.org/html/draft-ietf-webpush-encryption-09> also all apply to the use of the PushSubscription mechanism.