anil.recoil.org
this repo has no description
skeleton
+1
.gitignore
+1
.gitignore
···
1
+
_build
+18
dune-project
+18
dune-project
···
1
+
(lang dune 3.17)
2
+
(name jmap)
3
+
4
+
(source (github avsm/jmap))
5
+
(license ISC)
6
+
(authors "Anil Madhavapeddy")
7
+
(maintainers "anil@recoil.org")
8
+
9
+
(generate_opam_files true)
10
+
11
+
(package
12
+
(name jmap)
13
+
(synopsis "JMAP protocol")
14
+
(description "This is all still a work in progress")
15
+
(depends
16
+
(ocaml (>= "5.2.0"))
17
+
ezjsonm
18
+
ptime))
+31
jmap.opam
+31
jmap.opam
···
1
+
# This file is generated by dune, edit dune-project instead
2
+
opam-version: "2.0"
3
+
synopsis: "JMAP protocol"
4
+
description: "This is all still a work in progress"
5
+
maintainer: ["anil@recoil.org"]
6
+
authors: ["Anil Madhavapeddy"]
7
+
license: "ISC"
8
+
homepage: "https://github.com/avsm/jmap"
9
+
bug-reports: "https://github.com/avsm/jmap/issues"
10
+
depends: [
11
+
"dune" {>= "3.17"}
12
+
"ocaml" {>= "5.2.0"}
13
+
"ezjsonm"
14
+
"ptime"
15
+
"odoc" {with-doc}
16
+
]
17
+
build: [
18
+
["dune" "subst"] {dev}
19
+
[
20
+
"dune"
21
+
"build"
22
+
"-p"
23
+
name
24
+
"-j"
25
+
jobs
26
+
"@install"
27
+
"@runtest" {with-test}
28
+
"@doc" {with-doc}
29
+
]
30
+
]
31
+
dev-repo: "git+https://github.com/avsm/jmap.git"
lib/jmap.ml
lib/jmap.ml
This is a binary file and will not be displayed.
lib/jmap.mli
lib/jmap.mli
This is a binary file and will not be displayed.
+5043
spec/rfc8620.txt
+5043
spec/rfc8620.txt
···
1
+
2
+
3
+
4
+
5
+
6
+
7
+
Internet Engineering Task Force (IETF) N. Jenkins
8
+
Request for Comments: 8620 Fastmail
9
+
Category: Standards Track C. Newman
10
+
ISSN: 2070-1721 Oracle
11
+
July 2019
12
+
13
+
14
+
The JSON Meta Application Protocol (JMAP)
15
+
16
+
Abstract
17
+
18
+
This document specifies a protocol for clients to efficiently query,
19
+
fetch, and modify JSON-based data objects, with support for push
20
+
notification of changes and fast resynchronisation and for out-of-
21
+
band binary data upload/download.
22
+
23
+
Status of This Memo
24
+
25
+
This is an Internet Standards Track document.
26
+
27
+
This document is a product of the Internet Engineering Task Force
28
+
(IETF). It represents the consensus of the IETF community. It has
29
+
received public review and has been approved for publication by the
30
+
Internet Engineering Steering Group (IESG). Further information on
31
+
Internet Standards is available in Section 2 of RFC 7841.
32
+
33
+
Information about the current status of this document, any errata,
34
+
and how to provide feedback on it may be obtained at
35
+
https://www.rfc-editor.org/info/rfc8620.
36
+
37
+
Copyright Notice
38
+
39
+
Copyright (c) 2019 IETF Trust and the persons identified as the
40
+
document authors. All rights reserved.
41
+
42
+
This document is subject to BCP 78 and the IETF Trust's Legal
43
+
Provisions Relating to IETF Documents
44
+
(https://trustee.ietf.org/license-info) in effect on the date of
45
+
publication of this document. Please review these documents
46
+
carefully, as they describe your rights and restrictions with respect
47
+
to this document. Code Components extracted from this document must
48
+
include Simplified BSD License text as described in Section 4.e of
49
+
the Trust Legal Provisions and are provided without warranty as
50
+
described in the Simplified BSD License.
51
+
52
+
53
+
54
+
55
+
56
+
57
+
58
+
Jenkins & Newman Standards Track [Page 1]
59
+
60
+
RFC 8620 JMAP July 2019
61
+
62
+
63
+
Table of Contents
64
+
65
+
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
66
+
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
67
+
1.2. The Id Data Type . . . . . . . . . . . . . . . . . . . . 6
68
+
1.3. The Int and UnsignedInt Data Types . . . . . . . . . . . 6
69
+
1.4. The Date and UTCDate Data Types . . . . . . . . . . . . . 7
70
+
1.5. JSON as the Data Encoding Format . . . . . . . . . . . . 7
71
+
1.6. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7
72
+
1.6.1. User . . . . . . . . . . . . . . . . . . . . . . . . 7
73
+
1.6.2. Accounts . . . . . . . . . . . . . . . . . . . . . . 7
74
+
1.6.3. Data Types and Records . . . . . . . . . . . . . . . 8
75
+
1.7. The JMAP API Model . . . . . . . . . . . . . . . . . . . 8
76
+
1.8. Vendor-Specific Extensions . . . . . . . . . . . . . . . 9
77
+
2. The JMAP Session Resource . . . . . . . . . . . . . . . . . . 9
78
+
2.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 14
79
+
2.2. Service Autodiscovery . . . . . . . . . . . . . . . . . . 15
80
+
3. Structured Data Exchange . . . . . . . . . . . . . . . . . . 16
81
+
3.1. Making an API Request . . . . . . . . . . . . . . . . . . 16
82
+
3.2. The Invocation Data Type . . . . . . . . . . . . . . . . 16
83
+
3.3. The Request Object . . . . . . . . . . . . . . . . . . . 16
84
+
3.3.1. Example Request . . . . . . . . . . . . . . . . . . . 18
85
+
3.4. The Response Object . . . . . . . . . . . . . . . . . . . 18
86
+
3.4.1. Example Response . . . . . . . . . . . . . . . . . . 19
87
+
3.5. Omitting Arguments . . . . . . . . . . . . . . . . . . . 19
88
+
3.6. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 19
89
+
3.6.1. Request-Level Errors . . . . . . . . . . . . . . . . 20
90
+
3.6.2. Method-Level Errors . . . . . . . . . . . . . . . . . 21
91
+
3.7. References to Previous Method Results . . . . . . . . . . 22
92
+
3.8. Localisation of User-Visible Strings . . . . . . . . . . 27
93
+
3.9. Security . . . . . . . . . . . . . . . . . . . . . . . . 28
94
+
3.10. Concurrency . . . . . . . . . . . . . . . . . . . . . . . 28
95
+
4. The Core/echo Method . . . . . . . . . . . . . . . . . . . . 28
96
+
4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 28
97
+
5. Standard Methods and Naming Convention . . . . . . . . . . . 29
98
+
5.1. /get . . . . . . . . . . . . . . . . . . . . . . . . . . 29
99
+
5.2. /changes . . . . . . . . . . . . . . . . . . . . . . . . 30
100
+
5.3. /set . . . . . . . . . . . . . . . . . . . . . . . . . . 34
101
+
5.4. /copy . . . . . . . . . . . . . . . . . . . . . . . . . . 40
102
+
5.5. /query . . . . . . . . . . . . . . . . . . . . . . . . . 42
103
+
5.6. /queryChanges . . . . . . . . . . . . . . . . . . . . . . 48
104
+
5.7. Examples . . . . . . . . . . . . . . . . . . . . . . . . 51
105
+
5.8. Proxy Considerations . . . . . . . . . . . . . . . . . . 58
106
+
6. Binary Data . . . . . . . . . . . . . . . . . . . . . . . . . 58
107
+
6.1. Uploading Binary Data . . . . . . . . . . . . . . . . . . 59
108
+
6.2. Downloading Binary Data . . . . . . . . . . . . . . . . . 60
109
+
6.3. Blob/copy . . . . . . . . . . . . . . . . . . . . . . . . 61
110
+
111
+
112
+
113
+
114
+
Jenkins & Newman Standards Track [Page 2]
115
+
116
+
RFC 8620 JMAP July 2019
117
+
118
+
119
+
7. Push . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
120
+
7.1. The StateChange Object . . . . . . . . . . . . . . . . . 63
121
+
7.1.1. Example . . . . . . . . . . . . . . . . . . . . . . . 64
122
+
7.2. PushSubscription . . . . . . . . . . . . . . . . . . . . 64
123
+
7.2.1. PushSubscription/get . . . . . . . . . . . . . . . . 67
124
+
7.2.2. PushSubscription/set . . . . . . . . . . . . . . . . 68
125
+
7.2.3. Example . . . . . . . . . . . . . . . . . . . . . . . 69
126
+
7.3. Event Source . . . . . . . . . . . . . . . . . . . . . . 71
127
+
8. Security Considerations . . . . . . . . . . . . . . . . . . . 73
128
+
8.1. Transport Confidentiality . . . . . . . . . . . . . . . . 73
129
+
8.2. Authentication Scheme . . . . . . . . . . . . . . . . . . 73
130
+
8.3. Service Autodiscovery . . . . . . . . . . . . . . . . . . 73
131
+
8.4. JSON Parsing . . . . . . . . . . . . . . . . . . . . . . 74
132
+
8.5. Denial of Service . . . . . . . . . . . . . . . . . . . . 74
133
+
8.6. Connection to Unknown Push Server . . . . . . . . . . . . 74
134
+
8.7. Push Encryption . . . . . . . . . . . . . . . . . . . . . 75
135
+
8.8. Traffic Analysis . . . . . . . . . . . . . . . . . . . . 76
136
+
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 76
137
+
9.1. Assignment of jmap Service Name . . . . . . . . . . . . . 76
138
+
9.2. Registration of Well-Known URI Suffix for JMAP . . . . . 76
139
+
9.3. Registration of the jmap URN Sub-namespace . . . . . . . 77
140
+
9.4. Creation of "JMAP Capabilities" Registry . . . . . . . . 77
141
+
9.4.1. Preliminary Community Review . . . . . . . . . . . . 77
142
+
9.4.2. Submit Request to IANA . . . . . . . . . . . . . . . 78
143
+
9.4.3. Designated Expert Review . . . . . . . . . . . . . . 78
144
+
9.4.4. Change Procedures . . . . . . . . . . . . . . . . . . 78
145
+
9.4.5. JMAP Capabilities Registry Template . . . . . . . . . 79
146
+
9.4.6. Initial Registration for JMAP Core . . . . . . . . . 79
147
+
9.4.7. Registration for JMAP Error Placeholder in JMAP
148
+
Capabilities Registry . . . . . . . . . . . . . . . . 80
149
+
9.5. Creation of "JMAP Error Codes" Registry . . . . . . . . . 80
150
+
9.5.1. Expert Review . . . . . . . . . . . . . . . . . . . . 80
151
+
9.5.2. JMAP Error Codes Registry Template . . . . . . . . . 81
152
+
9.5.3. Initial Contents for the JMAP Error Codes Registry . 81
153
+
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 86
154
+
10.1. Normative References . . . . . . . . . . . . . . . . . . 86
155
+
10.2. Informative References . . . . . . . . . . . . . . . . . 89
156
+
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 90
157
+
158
+
159
+
160
+
161
+
162
+
163
+
164
+
165
+
166
+
167
+
168
+
169
+
170
+
Jenkins & Newman Standards Track [Page 3]
171
+
172
+
RFC 8620 JMAP July 2019
173
+
174
+
175
+
1. Introduction
176
+
177
+
The JSON Meta Application Protocol (JMAP) is used for synchronising
178
+
data, such as mail, calendars, or contacts, between a client and a
179
+
server. It is optimised for mobile and web environments and aims to
180
+
provide a consistent interface to different data types.
181
+
182
+
This specification is for the generic mechanism of data
183
+
synchronisation. Further specifications define the data models for
184
+
different data types that may be synchronised via JMAP.
185
+
186
+
JMAP is designed to make efficient use of limited network resources.
187
+
Multiple API calls may be batched in a single request to the server,
188
+
reducing round trips and improving battery life on mobile devices.
189
+
Push connections remove the need for polling, and an efficient delta
190
+
update mechanism ensures a minimum amount of data is transferred.
191
+
192
+
JMAP is designed to be horizontally scalable to a very large number
193
+
of users. This is facilitated by separate endpoints for users after
194
+
login, the separation of binary and structured data, and a data model
195
+
for sharing that does not allow data dependencies between accounts.
196
+
197
+
1.1. Notational Conventions
198
+
199
+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
200
+
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
201
+
"OPTIONAL" in this document are to be interpreted as described in
202
+
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
203
+
capitals, as shown here.
204
+
205
+
The underlying format used for this specification is JSON.
206
+
Consequently, the terms "object" and "array" as well as the four
207
+
primitive types (strings, numbers, booleans, and null) are to be
208
+
interpreted as described in Section 1 of [RFC8259]. Unless otherwise
209
+
noted, all the property names and values are case sensitive.
210
+
211
+
Some examples in this document contain "partial" JSON documents used
212
+
for illustrative purposes. In these examples, three periods "..."
213
+
are used to indicate a portion of the document that has been removed
214
+
for compactness.
215
+
216
+
For compatibility with publishing requirements, line breaks have been
217
+
inserted inside long JSON strings, with the following continuation
218
+
lines indented. To form the valid JSON example, any line breaks
219
+
inside a string must be replaced with a space and any other white
220
+
space after the line break removed.
221
+
222
+
223
+
224
+
225
+
226
+
Jenkins & Newman Standards Track [Page 4]
227
+
228
+
RFC 8620 JMAP July 2019
229
+
230
+
231
+
Unless otherwise specified, examples of API exchanges only show the
232
+
methodCalls array of the Request object or the methodResponses array
233
+
of the Response object. For compactness, the rest of the Request/
234
+
Response object is omitted.
235
+
236
+
Type signatures are given for all JSON values in this document. The
237
+
following conventions are used:
238
+
239
+
o "*" - The type is undefined (the value could be any type, although
240
+
permitted values may be constrained by the context of this value).
241
+
242
+
o "String" - The JSON string type.
243
+
244
+
o "Number" - The JSON number type.
245
+
246
+
o "Boolean" - The JSON boolean type.
247
+
248
+
o "A[B]" - A JSON object where the keys are all of type "A", and the
249
+
values are all of type "B".
250
+
251
+
o "A[]" - An array of values of type "A".
252
+
253
+
o "A|B" - The value is either of type "A" or of type "B".
254
+
255
+
Other types may also be given, with their representation defined
256
+
elsewhere in this document.
257
+
258
+
Object properties may also have a set of attributes defined along
259
+
with the type signature. These have the following meanings:
260
+
261
+
o "server-set" -- Only the server can set the value for this
262
+
property. The client MUST NOT send this property when creating a
263
+
new object of this type.
264
+
265
+
o "immutable" -- The value MUST NOT change after the object is
266
+
created.
267
+
268
+
o "default" -- (This is followed by a JSON value). The value that
269
+
will be used for this property if it is omitted in an argument or
270
+
when creating a new object of this type.
271
+
272
+
273
+
274
+
275
+
276
+
277
+
278
+
279
+
280
+
281
+
282
+
Jenkins & Newman Standards Track [Page 5]
283
+
284
+
RFC 8620 JMAP July 2019
285
+
286
+
287
+
1.2. The Id Data Type
288
+
289
+
All record ids are assigned by the server and are immutable.
290
+
291
+
Where "Id" is given as a data type, it means a "String" of at least 1
292
+
and a maximum of 255 octets in size, and it MUST only contain
293
+
characters from the "URL and Filename Safe" base64 alphabet, as
294
+
defined in Section 5 of [RFC4648], excluding the pad character ("=").
295
+
This means the allowed characters are the ASCII alphanumeric
296
+
characters ("A-Za-z0-9"), hyphen ("-"), and underscore ("_").
297
+
298
+
These characters are safe to use in almost any context (e.g.,
299
+
filesystems, URIs, and IMAP atoms). For maximum safety, servers
300
+
SHOULD also follow defensive allocation strategies to avoid creating
301
+
risks where glob completion or data type detection may be present
302
+
(e.g., on filesystems or in spreadsheets). In particular, it is wise
303
+
to avoid:
304
+
305
+
o Ids starting with a dash
306
+
307
+
o Ids starting with digits
308
+
309
+
o Ids that contain only digits
310
+
311
+
o Ids that differ only by ASCII case (for example, A vs. a)
312
+
313
+
o the specific sequence of three characters "NIL" (because this
314
+
sequence can be confused with the IMAP protocol expression of the
315
+
null value)
316
+
317
+
A good solution to these issues is to prefix every id with a single
318
+
alphabetical character.
319
+
320
+
1.3. The Int and UnsignedInt Data Types
321
+
322
+
Where "Int" is given as a data type, it means an integer in the range
323
+
-2^53+1 <= value <= 2^53-1, the safe range for integers stored in a
324
+
floating-point double, represented as a JSON "Number".
325
+
326
+
Where "UnsignedInt" is given as a data type, it means an "Int" where
327
+
the value MUST be in the range 0 <= value <= 2^53-1.
328
+
329
+
330
+
331
+
332
+
333
+
334
+
335
+
336
+
337
+
338
+
Jenkins & Newman Standards Track [Page 6]
339
+
340
+
RFC 8620 JMAP July 2019
341
+
342
+
343
+
1.4. The Date and UTCDate Data Types
344
+
345
+
Where "Date" is given as a type, it means a string in "date-time"
346
+
format [RFC3339]. To ensure a normalised form, the "time-secfrac"
347
+
MUST always be omitted if zero, and any letters in the string (e.g.,
348
+
"T" and "Z") MUST be uppercase. For example,
349
+
"2014-10-30T14:12:00+08:00".
350
+
351
+
Where "UTCDate" is given as a type, it means a "Date" where the
352
+
"time-offset" component MUST be "Z" (i.e., it must be in UTC time).
353
+
For example, "2014-10-30T06:12:00Z".
354
+
355
+
1.5. JSON as the Data Encoding Format
356
+
357
+
JSON is a text-based data interchange format as specified in
358
+
[RFC8259]. The Internet JSON (I-JSON) format defined in [RFC7493] is
359
+
a strict subset of this, adding restrictions to avoid potentially
360
+
confusing scenarios (for example, it mandates that an object MUST NOT
361
+
have two members with the same name).
362
+
363
+
All data sent from the client to the server or from the server to the
364
+
client (except binary file upload/download) MUST be valid I-JSON
365
+
according to the RFC and is therefore case sensitive and encoded in
366
+
UTF-8 [RFC3629].
367
+
368
+
1.6. Terminology
369
+
370
+
1.6.1. User
371
+
372
+
A user is a person accessing data via JMAP. A user has a set of
373
+
permissions determining the data that they can see.
374
+
375
+
1.6.2. Accounts
376
+
377
+
An account is a collection of data. A single account may contain an
378
+
arbitrary set of data types, for example, a collection of mail,
379
+
contacts, and calendars. Most JMAP methods take a mandatory
380
+
"accountId" argument that specifies on which account the operations
381
+
are to take place.
382
+
383
+
An account is not the same as a user, although it is common for a
384
+
primary account to directly belong to the user. For example, you may
385
+
have an account that contains data for a group or business, to which
386
+
multiple users have access.
387
+
388
+
389
+
390
+
391
+
392
+
393
+
394
+
Jenkins & Newman Standards Track [Page 7]
395
+
396
+
RFC 8620 JMAP July 2019
397
+
398
+
399
+
A single set of credentials may provide access to multiple accounts,
400
+
for example, if another user is sharing their work calendar with the
401
+
authenticated user or if there is a group mailbox for a support-desk
402
+
inbox.
403
+
404
+
In the event of a severe internal error, a server may have to
405
+
reallocate ids or do something else that violates standard JMAP data
406
+
constraints for an account. In this situation, the data on the
407
+
server is no longer compatible with cached data the client may have
408
+
from before. The server MUST treat this as though the account has
409
+
been deleted and then recreated with a new account id. Clients will
410
+
then be forced to throw away any data with the old account id and
411
+
refetch all data from scratch.
412
+
413
+
1.6.3. Data Types and Records
414
+
415
+
JMAP provides a uniform interface for creating, retrieving, updating,
416
+
and deleting various types of objects. A "data type" is a collection
417
+
of named, typed properties, just like the schema for a database
418
+
table. Each instance of a data type is called a "record".
419
+
420
+
The id of a record is immutable and assigned by the server. The id
421
+
MUST be unique among all records of the *same type* within the *same
422
+
account*. Ids may clash across accounts or for two records of
423
+
different types within the same account.
424
+
425
+
1.7. The JMAP API Model
426
+
427
+
JMAP uses HTTP [RFC7230] to expose API, push, upload, and download
428
+
resources. All HTTP requests MUST use the "https://" scheme (HTTP
429
+
over TLS [RFC2818]). All HTTP requests MUST be authenticated.
430
+
431
+
An authenticated client can fetch the user's Session object with
432
+
details about the data and capabilities the server can provide as
433
+
shown in Section 2. The client may then exchange data with the
434
+
server in the following ways:
435
+
436
+
1. The client may make an API request to the server to get or set
437
+
structured data. This request consists of an ordered series of
438
+
method calls. These are processed by the server, which then
439
+
returns an ordered series of responses. This is described in
440
+
Sections 3, 4, and 5.
441
+
442
+
2. The client may download or upload binary files from/to the
443
+
server. This is detailed in Section 6.
444
+
445
+
3. The client may connect to a push channel on the server, to be
446
+
notified when data has changed. This is explained in Section 7.
447
+
448
+
449
+
450
+
Jenkins & Newman Standards Track [Page 8]
451
+
452
+
RFC 8620 JMAP July 2019
453
+
454
+
455
+
1.8. Vendor-Specific Extensions
456
+
457
+
Individual services will have custom features they wish to expose
458
+
over JMAP. This may take the form of extra data types and/or methods
459
+
not in the spec, extra arguments to JMAP methods, or extra properties
460
+
on existing data types (which may also appear in arguments to methods
461
+
that take property names).
462
+
463
+
The server can advertise custom extensions it supports by including
464
+
the identifiers in the capabilities object. Identifiers for vendor
465
+
extensions MUST be a URL belonging to a domain owned by the vendor,
466
+
to avoid conflict. The URL SHOULD resolve to documentation for the
467
+
changes the extension makes.
468
+
469
+
The client MUST opt in to use an extension by passing the appropriate
470
+
capability identifier in the "using" array of the Request object, as
471
+
described in Section 3.3. The server MUST only follow the
472
+
specifications that are opted into and behave as though it does not
473
+
implement anything else when processing a request. This is to ensure
474
+
compatibility with clients that don't know about a specific custom
475
+
extension and for compatibility with future versions of JMAP.
476
+
477
+
2. The JMAP Session Resource
478
+
479
+
You need two things to connect to a JMAP server:
480
+
481
+
1. The URL for the JMAP Session resource. This may be requested
482
+
directly from the user or discovered automatically based on a
483
+
username domain (see Section 2.2 below).
484
+
485
+
2. Credentials to authenticate with. How to obtain credentials is
486
+
out of scope for this document.
487
+
488
+
A successful authenticated GET request to the JMAP Session resource
489
+
MUST return a JSON-encoded *Session* object, giving details about the
490
+
data and capabilities the server can provide to the client given
491
+
those credentials. It has the following properties:
492
+
493
+
o capabilities: "String[Object]"
494
+
495
+
An object specifying the capabilities of this server. Each key is
496
+
a URI for a capability supported by the server. The value for
497
+
each of these keys is an object with further information about the
498
+
server's capabilities in relation to that capability.
499
+
500
+
The client MUST ignore any properties it does not understand.
501
+
502
+
503
+
504
+
505
+
506
+
Jenkins & Newman Standards Track [Page 9]
507
+
508
+
RFC 8620 JMAP July 2019
509
+
510
+
511
+
The capabilities object MUST include a property called
512
+
"urn:ietf:params:jmap:core". The value of this property is an
513
+
object that MUST contain the following information on server
514
+
capabilities (suggested minimum values for limits are supplied
515
+
that allow clients to make efficient use of the network):
516
+
517
+
* maxSizeUpload: "UnsignedInt"
518
+
519
+
The maximum file size, in octets, that the server will accept
520
+
for a single file upload (for any purpose). Suggested minimum:
521
+
50,000,000.
522
+
523
+
* maxConcurrentUpload: "UnsignedInt"
524
+
525
+
The maximum number of concurrent requests the server will
526
+
accept to the upload endpoint. Suggested minimum: 4.
527
+
528
+
* maxSizeRequest: "UnsignedInt"
529
+
530
+
The maximum size, in octets, that the server will accept for a
531
+
single request to the API endpoint. Suggested minimum:
532
+
10,000,000.
533
+
534
+
* maxConcurrentRequests: "UnsignedInt"
535
+
536
+
The maximum number of concurrent requests the server will
537
+
accept to the API endpoint. Suggested minimum: 4.
538
+
539
+
* maxCallsInRequest: "UnsignedInt"
540
+
541
+
The maximum number of method calls the server will accept in a
542
+
single request to the API endpoint. Suggested minimum: 16.
543
+
544
+
* maxObjectsInGet: "UnsignedInt"
545
+
546
+
The maximum number of objects that the client may request in a
547
+
single /get type method call. Suggested minimum: 500.
548
+
549
+
* maxObjectsInSet: "UnsignedInt"
550
+
551
+
The maximum number of objects the client may send to create,
552
+
update, or destroy in a single /set type method call. This is
553
+
the combined total, e.g., if the maximum is 10, you could not
554
+
create 7 objects and destroy 6, as this would be 13 actions,
555
+
which exceeds the limit. Suggested minimum: 500.
556
+
557
+
558
+
559
+
560
+
561
+
562
+
Jenkins & Newman Standards Track [Page 10]
563
+
564
+
RFC 8620 JMAP July 2019
565
+
566
+
567
+
* collationAlgorithms: "String[]"
568
+
569
+
A list of identifiers for algorithms registered in the
570
+
collation registry, as defined in [RFC4790], that the server
571
+
supports for sorting when querying records.
572
+
573
+
Specifications for future capabilities will define their own
574
+
properties on the capabilities object.
575
+
576
+
Servers MAY advertise vendor-specific JMAP extensions, as
577
+
described in Section 1.8. To avoid conflict, an identifier for a
578
+
vendor-specific extension MUST be a URL with a domain owned by the
579
+
vendor. Clients MUST opt in to any capability it wishes to use
580
+
(see Section 3.3).
581
+
582
+
o accounts: "Id[Account]"
583
+
584
+
A map of an account id to an Account object for each account (see
585
+
Section 1.6.2) the user has access to. An *Account* object has
586
+
the following properties:
587
+
588
+
* name: "String"
589
+
590
+
A user-friendly string to show when presenting content from
591
+
this account, e.g., the email address representing the owner of
592
+
the account.
593
+
594
+
* isPersonal: "Boolean"
595
+
596
+
This is true if the account belongs to the authenticated user
597
+
rather than a group account or a personal account of another
598
+
user that has been shared with them.
599
+
600
+
* isReadOnly: "Boolean"
601
+
602
+
This is true if the entire account is read-only.
603
+
604
+
* accountCapabilities: "String[Object]"
605
+
606
+
The set of capability URIs for the methods supported in this
607
+
account. Each key is a URI for a capability that has methods
608
+
you can use with this account. The value for each of these
609
+
keys is an object with further information about the account's
610
+
permissions and restrictions with respect to this capability,
611
+
as defined in the capability's specification.
612
+
613
+
The client MUST ignore any properties it does not understand.
614
+
615
+
616
+
617
+
618
+
Jenkins & Newman Standards Track [Page 11]
619
+
620
+
RFC 8620 JMAP July 2019
621
+
622
+
623
+
The server advertises the full list of capabilities it supports
624
+
in the capabilities object, as defined above. If the
625
+
capability defines new methods, the server MUST include it in
626
+
the accountCapabilities object if the user may use those
627
+
methods with this account. It MUST NOT include it in the
628
+
accountCapabilities object if the user cannot use those methods
629
+
with this account.
630
+
631
+
For example, you may have access to your own account with mail,
632
+
calendars, and contacts data and also a shared account that
633
+
only has contacts data (a business address book, for example).
634
+
In this case, the accountCapabilities property on the first
635
+
account would include something like
636
+
"urn:ietf:params:jmap:mail", "urn:ietf:params:jmap:calendars",
637
+
and "urn:ietf:params:jmap:contacts", while the second account
638
+
would just have the last of these.
639
+
640
+
Attempts to use the methods defined in a capability with one of
641
+
the accounts that does not support that capability are rejected
642
+
with an "accountNotSupportedByMethod" error (see "Method-Level
643
+
Errors", Section 3.6.2).
644
+
645
+
o primaryAccounts: "String[Id]"
646
+
647
+
A map of capability URIs (as found in accountCapabilities) to the
648
+
account id that is considered to be the user's main or default
649
+
account for data pertaining to that capability. If no account
650
+
being returned belongs to the user, or in any other way there is
651
+
no appropriate way to determine a default account, there MAY be no
652
+
entry for a particular URI, even though that capability is
653
+
supported by the server (and in the capabilities object).
654
+
"urn:ietf:params:jmap:core" SHOULD NOT be present.
655
+
656
+
o username: "String"
657
+
658
+
The username associated with the given credentials, or the empty
659
+
string if none.
660
+
661
+
o apiUrl: "String"
662
+
663
+
The URL to use for JMAP API requests.
664
+
665
+
666
+
667
+
668
+
669
+
670
+
671
+
672
+
673
+
674
+
Jenkins & Newman Standards Track [Page 12]
675
+
676
+
RFC 8620 JMAP July 2019
677
+
678
+
679
+
o downloadUrl: "String"
680
+
681
+
The URL endpoint to use when downloading files, in URI Template
682
+
(level 1) format [RFC6570]. The URL MUST contain variables called
683
+
"accountId", "blobId", "type", and "name". The use of these
684
+
variables is described in Section 6.2. Due to potential encoding
685
+
issues with slashes in content types, it is RECOMMENDED to put the
686
+
"type" variable in the query section of the URL.
687
+
688
+
o uploadUrl: "String"
689
+
690
+
The URL endpoint to use when uploading files, in URI Template
691
+
(level 1) format [RFC6570]. The URL MUST contain a variable
692
+
called "accountId". The use of this variable is described in
693
+
Section 6.1.
694
+
695
+
o eventSourceUrl: "String"
696
+
697
+
The URL to connect to for push events, as described in
698
+
Section 7.3, in URI Template (level 1) format [RFC6570]. The URL
699
+
MUST contain variables called "types", "closeafter", and "ping".
700
+
The use of these variables is described in Section 7.3.
701
+
702
+
o state: "String"
703
+
704
+
A (preferably short) string representing the state of this object
705
+
on the server. If the value of any other property on the Session
706
+
object changes, this string will change. The current value is
707
+
also returned on the API Response object (see Section 3.4),
708
+
allowing clients to quickly determine if the session information
709
+
has changed (e.g., an account has been added or removed), so they
710
+
need to refetch the object.
711
+
712
+
To ensure future compatibility, other properties MAY be included on
713
+
the Session object. Clients MUST ignore any properties they are not
714
+
expecting.
715
+
716
+
Implementors must take care to avoid inappropriate caching of the
717
+
Session object at the HTTP layer. Since the client should only
718
+
refetch when it detects there is a change (via the sessionState
719
+
property of an API response), it is RECOMMENDED to disable HTTP
720
+
caching altogether, for example, by setting "Cache-Control: no-cache,
721
+
no-store, must-revalidate" on the response.
722
+
723
+
724
+
725
+
726
+
727
+
728
+
729
+
730
+
Jenkins & Newman Standards Track [Page 13]
731
+
732
+
RFC 8620 JMAP July 2019
733
+
734
+
735
+
2.1. Example
736
+
737
+
In the following example Session object, the user has access to their
738
+
own mail and contacts via JMAP, as well as read-only access to shared
739
+
mail from another user. The server is advertising a custom
740
+
"https://example.com/apis/foobar" capability.
741
+
742
+
{
743
+
"capabilities": {
744
+
"urn:ietf:params:jmap:core": {
745
+
"maxSizeUpload": 50000000,
746
+
"maxConcurrentUpload": 8,
747
+
"maxSizeRequest": 10000000,
748
+
"maxConcurrentRequest": 8,
749
+
"maxCallsInRequest": 32,
750
+
"maxObjectsInGet": 256,
751
+
"maxObjectsInSet": 128,
752
+
"collationAlgorithms": [
753
+
"i;ascii-numeric",
754
+
"i;ascii-casemap",
755
+
"i;unicode-casemap"
756
+
]
757
+
},
758
+
"urn:ietf:params:jmap:mail": {}
759
+
"urn:ietf:params:jmap:contacts": {},
760
+
"https://example.com/apis/foobar": {
761
+
"maxFoosFinangled": 42
762
+
}
763
+
},
764
+
"accounts": {
765
+
"A13824": {
766
+
"name": "john@example.com",
767
+
"isPersonal": true,
768
+
"isReadOnly": false,
769
+
"accountCapabilities": {
770
+
"urn:ietf:params:jmap:mail": {
771
+
"maxMailboxesPerEmail": null,
772
+
"maxMailboxDepth": 10,
773
+
...
774
+
},
775
+
"urn:ietf:params:jmap:contacts": {
776
+
...
777
+
}
778
+
}
779
+
},
780
+
781
+
782
+
783
+
784
+
785
+
786
+
Jenkins & Newman Standards Track [Page 14]
787
+
788
+
RFC 8620 JMAP July 2019
789
+
790
+
791
+
"A97813": {
792
+
"name": "jane@example.com",
793
+
"isPersonal": false,
794
+
"isReadOnly": true,
795
+
"accountCapabilities": {
796
+
"urn:ietf:params:jmap:mail": {
797
+
"maxMailboxesPerEmail": 1,
798
+
"maxMailboxDepth": 10,
799
+
...
800
+
}
801
+
}
802
+
}
803
+
},
804
+
"primaryAccounts": {
805
+
"urn:ietf:params:jmap:mail": "A13824",
806
+
"urn:ietf:params:jmap:contacts": "A13824"
807
+
},
808
+
"username": "john@example.com",
809
+
"apiUrl": "https://jmap.example.com/api/",
810
+
"downloadUrl": "https://jmap.example.com
811
+
/download/{accountId}/{blobId}/{name}?accept={type}",
812
+
"uploadUrl": "https://jmap.example.com/upload/{accountId}/",
813
+
"eventSourceUrl": "https://jmap.example.com
814
+
/eventsource/?types={types}&closeafter={closeafter}&ping={ping}",
815
+
"state": "75128aab4b1b"
816
+
}
817
+
818
+
2.2. Service Autodiscovery
819
+
820
+
There are two standardised autodiscovery methods in use for Internet
821
+
protocols:
822
+
823
+
o DNS SRV (see [RFC2782], [RFC6186], and [RFC6764])
824
+
825
+
o .well-known/servicename (see [RFC8615])
826
+
827
+
A JMAP-supporting host for the domain "example.com" SHOULD publish a
828
+
SRV record "_jmap._tcp.example.com" that gives a hostname and port
829
+
(usually port "443"). The JMAP Session resource is then
830
+
"https://${hostname}[:${port}]/.well-known/jmap" (following any
831
+
redirects).
832
+
833
+
If the client has a username in the form of an email address, it MAY
834
+
use the domain portion of this to attempt autodiscovery of the JMAP
835
+
server.
836
+
837
+
838
+
839
+
840
+
841
+
842
+
Jenkins & Newman Standards Track [Page 15]
843
+
844
+
RFC 8620 JMAP July 2019
845
+
846
+
847
+
3. Structured Data Exchange
848
+
849
+
The client may make an API request to the server to get or set
850
+
structured data. This request consists of an ordered series of
851
+
method calls. These are processed by the server, which then returns
852
+
an ordered series of responses.
853
+
854
+
3.1. Making an API Request
855
+
856
+
To make an API request, the client makes an authenticated POST
857
+
request to the API resource, which is defined by the "apiUrl"
858
+
property in the Session object (see Section 2).
859
+
860
+
The request MUST be of type "application/json" and consist of a
861
+
single JSON-encoded "Request" object, as defined in Section 3.3. If
862
+
successful, the response MUST also be of type "application/json" and
863
+
consist of a single "Response" object, as defined in Section 3.4.
864
+
865
+
3.2. The Invocation Data Type
866
+
867
+
Method calls and responses are represented by the *Invocation* data
868
+
type. This is a tuple, represented as a JSON array containing three
869
+
elements:
870
+
871
+
1. A "String" *name* of the method to call or of the response.
872
+
873
+
2. A "String[*]" object containing named *arguments* for that method
874
+
or response.
875
+
876
+
3. A "String" *method call id*: an arbitrary string from the client
877
+
to be echoed back with the responses emitted by that method call
878
+
(a method may return 1 or more responses, as it may make implicit
879
+
calls to other methods; all responses initiated by this method
880
+
call get the same method call id in the response).
881
+
882
+
3.3. The Request Object
883
+
884
+
A *Request* object has the following properties:
885
+
886
+
o using: "String[]"
887
+
888
+
The set of capabilities the client wishes to use. The client MAY
889
+
include capability identifiers even if the method calls it makes
890
+
do not utilise those capabilities. The server advertises the set
891
+
of specifications it supports in the Session object (see
892
+
Section 2), as keys on the "capabilities" property.
893
+
894
+
895
+
896
+
897
+
898
+
Jenkins & Newman Standards Track [Page 16]
899
+
900
+
RFC 8620 JMAP July 2019
901
+
902
+
903
+
o methodCalls: "Invocation[]"
904
+
905
+
An array of method calls to process on the server. The method
906
+
calls MUST be processed sequentially, in order.
907
+
908
+
o createdIds: "Id[Id]" (optional)
909
+
910
+
A map of a (client-specified) creation id to the id the server
911
+
assigned when a record was successfully created.
912
+
913
+
As described later in this specification, some records may have a
914
+
property that contains the id of another record. To allow more
915
+
efficient network usage, you can set this property to reference a
916
+
record created earlier in the same API request. Since the real id
917
+
is unknown when the request is created, the client can instead
918
+
specify the creation id it assigned, prefixed with a "#" (see
919
+
Section 5.3 for more details).
920
+
921
+
As the server processes API requests, any time it successfully
922
+
creates a new record, it adds the creation id to this map (see the
923
+
"create" argument to /set in Section 5.3), with the server-
924
+
assigned real id as the value. If it comes across a reference to
925
+
a creation id in a create/update, it looks it up in the map and
926
+
replaces the reference with the real id, if found.
927
+
928
+
The client can pass an initial value for this map as the
929
+
"createdIds" property of the Request object. This may be an empty
930
+
object. If given in the request, the response will also include a
931
+
createdIds property. This allows proxy servers to easily split a
932
+
JMAP request into multiple JMAP requests to send to different
933
+
servers. For example, it could send the first two method calls to
934
+
server A, then the third to server B, before sending the fourth to
935
+
server A again. By passing the createdIds of the previous
936
+
response to the next request, it can ensure all of these still
937
+
resolve. See Section 5.8 for further discussion of proxy
938
+
considerations.
939
+
940
+
Future specifications MAY add further properties to the Request
941
+
object to extend the semantics. To ensure forwards compatibility, a
942
+
server MUST ignore any other properties it does not understand on the
943
+
JMAP Request object.
944
+
945
+
946
+
947
+
948
+
949
+
950
+
951
+
952
+
953
+
954
+
Jenkins & Newman Standards Track [Page 17]
955
+
956
+
RFC 8620 JMAP July 2019
957
+
958
+
959
+
3.3.1. Example Request
960
+
961
+
{
962
+
"using": [ "urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail" ],
963
+
"methodCalls": [
964
+
[ "method1", {
965
+
"arg1": "arg1data",
966
+
"arg2": "arg2data"
967
+
}, "c1" ],
968
+
[ "method2", {
969
+
"arg1": "arg1data"
970
+
}, "c2" ],
971
+
[ "method3", {}, "c3" ]
972
+
]
973
+
}
974
+
975
+
3.4. The Response Object
976
+
977
+
A *Response* object has the following properties:
978
+
979
+
o methodResponses: "Invocation[]"
980
+
981
+
An array of responses, in the same format as the "methodCalls" on
982
+
the Request object. The output of the methods MUST be added to
983
+
the "methodResponses" array in the same order that the methods are
984
+
processed.
985
+
986
+
o createdIds: "Id[Id]" (optional; only returned if given in the
987
+
request)
988
+
989
+
A map of a (client-specified) creation id to the id the server
990
+
assigned when a record was successfully created. This MUST
991
+
include all creation ids passed in the original createdIds
992
+
parameter of the Request object, as well as any additional ones
993
+
added for newly created records.
994
+
995
+
o sessionState: "String"
996
+
997
+
The current value of the "state" string on the Session object, as
998
+
described in Section 2. Clients may use this to detect if this
999
+
object has changed and needs to be refetched.
1000
+
1001
+
Unless otherwise specified, if the method call completed
1002
+
successfully, its response name is the same as the method name in the
1003
+
request.
1004
+
1005
+
1006
+
1007
+
1008
+
1009
+
1010
+
Jenkins & Newman Standards Track [Page 18]
1011
+
1012
+
RFC 8620 JMAP July 2019
1013
+
1014
+
1015
+
3.4.1. Example Response
1016
+
1017
+
{
1018
+
"methodResponses": [
1019
+
[ "method1", {
1020
+
"arg1": 3,
1021
+
"arg2": "foo"
1022
+
}, "c1" ],
1023
+
[ "method2", {
1024
+
"isBlah": true
1025
+
}, "c2" ],
1026
+
[ "anotherResponseFromMethod2", {
1027
+
"data": 10,
1028
+
"yetmoredata": "Hello"
1029
+
}, "c2"],
1030
+
[ "error", {
1031
+
"type":"unknownMethod"
1032
+
}, "c3" ]
1033
+
],
1034
+
"sessionState": "75128aab4b1b"
1035
+
}
1036
+
1037
+
3.5. Omitting Arguments
1038
+
1039
+
An argument to a method may be specified to have a default value. If
1040
+
omitted by the client, the server MUST treat the method call the same
1041
+
as if the default value had been specified. Similarly, the server
1042
+
MAY omit any argument in a response that has the default value.
1043
+
1044
+
Unless otherwise specified in a method description, null is the
1045
+
default value for any argument in a request or response where this is
1046
+
allowed by the type signature. Other arguments may only be omitted
1047
+
if an explicit default value is defined in the method description.
1048
+
1049
+
3.6. Errors
1050
+
1051
+
There are three different levels of granularity at which an error may
1052
+
be returned in JMAP.
1053
+
1054
+
When an API request is made, the request as a whole may be rejected
1055
+
due to rate limiting, malformed JSON, request for an unknown
1056
+
capability, etc. In this case, the entire request is rejected with
1057
+
an appropriate HTTP error response code and an additional JSON body
1058
+
with more detail for the client.
1059
+
1060
+
Provided the request itself is syntactically valid (the JSON is valid
1061
+
and when decoded, it matches the type signature of a Request object),
1062
+
the methods within it are executed sequentially by the server. Each
1063
+
1064
+
1065
+
1066
+
Jenkins & Newman Standards Track [Page 19]
1067
+
1068
+
RFC 8620 JMAP July 2019
1069
+
1070
+
1071
+
method may individually fail, for example, if invalid arguments are
1072
+
given or an unknown method name is called.
1073
+
1074
+
Finally, methods that make changes to the server state often act upon
1075
+
a number of different records within a single call. Each record
1076
+
change may be separately rejected with a SetError, as described in
1077
+
Section 5.3.
1078
+
1079
+
3.6.1. Request-Level Errors
1080
+
1081
+
When an HTTP error response is returned to the client, the server
1082
+
SHOULD return a JSON "problem details" object as the response body,
1083
+
as per [RFC7807].
1084
+
1085
+
The following problem types are defined:
1086
+
1087
+
o "urn:ietf:params:jmap:error:unknownCapability"
1088
+
The client included a capability in the "using" property of the
1089
+
request that the server does not support.
1090
+
1091
+
o "urn:ietf:params:jmap:error:notJSON"
1092
+
The content type of the request was not "application/json" or the
1093
+
request did not parse as I-JSON.
1094
+
1095
+
o "urn:ietf:params:jmap:error:notRequest"
1096
+
The request parsed as JSON but did not match the type signature of
1097
+
the Request object.
1098
+
1099
+
o "urn:ietf:params:jmap:error:limit"
1100
+
The request was not processed as it would have exceeded one of the
1101
+
request limits defined on the capability object, such as
1102
+
maxSizeRequest, maxCallsInRequest, or maxConcurrentRequests. A
1103
+
"limit" property MUST also be present on the "problem details"
1104
+
object, containing the name of the limit being applied.
1105
+
1106
+
3.6.1.1. Example
1107
+
1108
+
{
1109
+
"type": "urn:ietf:params:jmap:error:unknownCapability",
1110
+
"status": 400,
1111
+
"detail": "The Request object used capability
1112
+
'https://example.com/apis/foobar', which is not supported
1113
+
by this server."
1114
+
}
1115
+
1116
+
1117
+
1118
+
1119
+
1120
+
1121
+
1122
+
Jenkins & Newman Standards Track [Page 20]
1123
+
1124
+
RFC 8620 JMAP July 2019
1125
+
1126
+
1127
+
Another example:
1128
+
1129
+
{
1130
+
"type": "urn:ietf:params:jmap:error:limit",
1131
+
"limit": "maxSizeRequest",
1132
+
"status": 400,
1133
+
"detail": "The request is larger than the server is willing to
1134
+
process."
1135
+
}
1136
+
1137
+
3.6.2. Method-Level Errors
1138
+
1139
+
If a method encounters an error, the appropriate "error" response
1140
+
MUST be inserted at the current point in the "methodResponses" array
1141
+
and, unless otherwise specified, further processing MUST NOT happen
1142
+
within that method call.
1143
+
1144
+
Any further method calls in the request MUST then be processed as
1145
+
normal. Errors at the method level MUST NOT generate an HTTP-level
1146
+
error.
1147
+
1148
+
An "error" response looks like this:
1149
+
1150
+
[ "error", {
1151
+
"type": "unknownMethod"
1152
+
}, "call-id" ]
1153
+
1154
+
The response name is "error", and it MUST have a type property.
1155
+
Other properties may be present with further information; these are
1156
+
detailed in the error type descriptions where appropriate.
1157
+
1158
+
With the exception of when the "serverPartialFail" error is returned,
1159
+
the externally visible state of the server MUST NOT have changed if
1160
+
an error is returned at the method level.
1161
+
1162
+
The following error types are defined, which may be returned for any
1163
+
method call where appropriate:
1164
+
1165
+
"serverUnavailable": Some internal server resource was temporarily
1166
+
unavailable. Attempting the same operation later (perhaps after a
1167
+
backoff with a random factor) may succeed.
1168
+
1169
+
"serverFail": An unexpected or unknown error occurred during the
1170
+
processing of the call. A "description" property should provide more
1171
+
details about the error. The method call made no changes to the
1172
+
server's state. Attempting the same operation again is expected to
1173
+
fail again. Contacting the service administrator is likely necessary
1174
+
to resolve this problem if it is persistent.
1175
+
1176
+
1177
+
1178
+
Jenkins & Newman Standards Track [Page 21]
1179
+
1180
+
RFC 8620 JMAP July 2019
1181
+
1182
+
1183
+
"serverPartialFail": Some, but not all, expected changes described by
1184
+
the method occurred. The client MUST resynchronise impacted data to
1185
+
determine server state. Use of this error is strongly discouraged.
1186
+
1187
+
"unknownMethod": The server does not recognise this method name.
1188
+
1189
+
"invalidArguments": One of the arguments is of the wrong type or is
1190
+
otherwise invalid, or a required argument is missing. A
1191
+
"description" property MAY be present to help debug with an
1192
+
explanation of what the problem was. This is a non-localised string,
1193
+
and it is not intended to be shown directly to end users.
1194
+
1195
+
"invalidResultReference": The method used a result reference for one
1196
+
of its arguments (see Section 3.7), but this failed to resolve.
1197
+
1198
+
"forbidden": The method and arguments are valid, but executing the
1199
+
method would violate an Access Control List (ACL) or other
1200
+
permissions policy.
1201
+
1202
+
"accountNotFound": The accountId does not correspond to a valid
1203
+
account.
1204
+
1205
+
"accountNotSupportedByMethod": The accountId given corresponds to a
1206
+
valid account, but the account does not support this method or data
1207
+
type.
1208
+
1209
+
"accountReadOnly": This method modifies state, but the account is
1210
+
read-only (as returned on the corresponding Account object in the
1211
+
JMAP Session resource).
1212
+
1213
+
Further possible errors for a particular method are specified in the
1214
+
method descriptions.
1215
+
1216
+
Further general errors MAY be defined in future RFCs. Should a
1217
+
client receive an error type it does not understand, it MUST treat it
1218
+
the same as the "serverFail" type.
1219
+
1220
+
3.7. References to Previous Method Results
1221
+
1222
+
To allow clients to make more efficient use of the network and avoid
1223
+
round trips, an argument to one method can be taken from the result
1224
+
of a previous method call in the same request.
1225
+
1226
+
To do this, the client prefixes the argument name with "#" (an
1227
+
octothorpe). The value is a ResultReference object as described
1228
+
below. When processing a method call, the server MUST first check
1229
+
the arguments object for any names beginning with "#". If found, the
1230
+
result reference should be resolved and the value used as the "real"
1231
+
1232
+
1233
+
1234
+
Jenkins & Newman Standards Track [Page 22]
1235
+
1236
+
RFC 8620 JMAP July 2019
1237
+
1238
+
1239
+
argument. The method is then processed as normal. If any result
1240
+
reference fails to resolve, the whole method MUST be rejected with an
1241
+
"invalidResultReference" error. If an arguments object contains the
1242
+
same argument name in normal and referenced form (e.g., "foo" and
1243
+
"#foo"), the method MUST return an "invalidArguments" error.
1244
+
1245
+
A *ResultReference* object has the following properties:
1246
+
1247
+
o resultOf: "String"
1248
+
1249
+
The method call id (see Section 3.2) of a previous method call in
1250
+
the current request.
1251
+
1252
+
o name: "String"
1253
+
1254
+
The required name of a response to that method call.
1255
+
1256
+
o path: "String"
1257
+
1258
+
A pointer into the arguments of the response selected via the name
1259
+
and resultOf properties. This is a JSON Pointer [RFC6901], except
1260
+
it also allows the use of "*" to map through an array (see the
1261
+
description below).
1262
+
1263
+
To resolve:
1264
+
1265
+
1. Find the first response with a method call id identical to the
1266
+
"resultOf" property of the ResultReference in the
1267
+
"methodResponses" array from previously processed method calls in
1268
+
the same request. If none, evaluation fails.
1269
+
1270
+
2. If the response name is not identical to the "name" property of
1271
+
the ResultReference, evaluation fails.
1272
+
1273
+
3. Apply the "path" to the arguments object of the response (the
1274
+
second item in the response array) following the JSON Pointer
1275
+
algorithm [RFC6901], except with the following addition in
1276
+
"Evaluation" (see Section 4):
1277
+
1278
+
If the currently referenced value is a JSON array, the reference
1279
+
token may be exactly the single character "*", making the new
1280
+
referenced value the result of applying the rest of the JSON
1281
+
Pointer tokens to every item in the array and returning the
1282
+
results in the same order in a new array. If the result of
1283
+
applying the rest of the pointer tokens to each item was itself
1284
+
an array, the contents of this array are added to the output
1285
+
rather than the array itself (i.e., the result is flattened from
1286
+
an array of arrays to a single array). If the result of applying
1287
+
1288
+
1289
+
1290
+
Jenkins & Newman Standards Track [Page 23]
1291
+
1292
+
RFC 8620 JMAP July 2019
1293
+
1294
+
1295
+
the rest of the pointer tokens to a value was itself an array,
1296
+
its items should be included individually in the output rather
1297
+
than including the array itself (i.e., the result is flattened
1298
+
from an array of arrays to a single array).
1299
+
1300
+
As a simple example, suppose we have the following API request
1301
+
"methodCalls":
1302
+
1303
+
[[ "Foo/changes", {
1304
+
"accountId": "A1",
1305
+
"sinceState": "abcdef"
1306
+
}, "t0" ],
1307
+
[ "Foo/get", {
1308
+
"accountId": "A1",
1309
+
"#ids": {
1310
+
"resultOf": "t0",
1311
+
"name": "Foo/changes",
1312
+
"path": "/created"
1313
+
}
1314
+
}, "t1" ]]
1315
+
1316
+
After executing the first method call, the "methodResponses" array
1317
+
is:
1318
+
1319
+
[[ "Foo/changes", {
1320
+
"accountId": "A1",
1321
+
"oldState": "abcdef",
1322
+
"newState": "123456",
1323
+
"hasMoreChanges": false,
1324
+
"created": [ "f1", "f4" ],
1325
+
"updated": [],
1326
+
"destroyed": []
1327
+
}, "t0" ]]
1328
+
1329
+
To execute the "Foo/get" call, we look through the arguments and find
1330
+
there is one with a "#" prefix. To resolve this, we apply the
1331
+
algorithm above:
1332
+
1333
+
1. Find the first response with method call id "t0". The "Foo/
1334
+
changes" response fulfils this criterion.
1335
+
1336
+
2. Check that the response name is the same as in the result
1337
+
reference. It is, so this is fine.
1338
+
1339
+
3. Apply the "path" as a JSON Pointer to the arguments object. This
1340
+
simply selects the "created" property, so the result of
1341
+
evaluating is: [ "f1", "f4" ].
1342
+
1343
+
1344
+
1345
+
1346
+
Jenkins & Newman Standards Track [Page 24]
1347
+
1348
+
RFC 8620 JMAP July 2019
1349
+
1350
+
1351
+
The JMAP server now continues to process the "Foo/get" call as though
1352
+
the arguments were:
1353
+
1354
+
{
1355
+
"accountId": "A1",
1356
+
"ids": [ "f1", "f4" ]
1357
+
}
1358
+
1359
+
Now, a more complicated example using the JMAP Mail data model: fetch
1360
+
the "from"/"date"/"subject" for every Email in the first 10 Threads
1361
+
in the inbox (sorted newest first):
1362
+
1363
+
[[ "Email/query", {
1364
+
"accountId": "A1",
1365
+
"filter": { "inMailbox": "id_of_inbox" },
1366
+
"sort": [{ "property": "receivedAt", "isAscending": false }],
1367
+
"collapseThreads": true,
1368
+
"position": 0,
1369
+
"limit": 10,
1370
+
"calculateTotal": true
1371
+
}, "t0" ],
1372
+
[ "Email/get", {
1373
+
"accountId": "A1",
1374
+
"#ids": {
1375
+
"resultOf": "t0",
1376
+
"name": "Email/query",
1377
+
"path": "/ids"
1378
+
},
1379
+
"properties": [ "threadId" ]
1380
+
}, "t1" ],
1381
+
[ "Thread/get", {
1382
+
"accountId": "A1",
1383
+
"#ids": {
1384
+
"resultOf": "t1",
1385
+
"name": "Email/get",
1386
+
"path": "/list/*/threadId"
1387
+
}
1388
+
}, "t2" ],
1389
+
[ "Email/get", {
1390
+
"accountId": "A1",
1391
+
"#ids": {
1392
+
"resultOf": "t2",
1393
+
"name": "Thread/get",
1394
+
"path": "/list/*/emailIds"
1395
+
},
1396
+
"properties": [ "from", "receivedAt", "subject" ]
1397
+
}, "t3" ]]
1398
+
1399
+
1400
+
1401
+
1402
+
Jenkins & Newman Standards Track [Page 25]
1403
+
1404
+
RFC 8620 JMAP July 2019
1405
+
1406
+
1407
+
After executing the first 3 method calls, the "methodResponses" array
1408
+
might be:
1409
+
1410
+
[[ "Email/query", {
1411
+
"accountId": "A1",
1412
+
"queryState": "abcdefg",
1413
+
"canCalculateChanges": true,
1414
+
"position": 0,
1415
+
"total": 101,
1416
+
"ids": [ "msg1023", "msg223", "msg110", "msg93", "msg91",
1417
+
"msg38", "msg36", "msg33", "msg11", "msg1" ]
1418
+
}, "t0" ],
1419
+
[ "Email/get", {
1420
+
"accountId": "A1",
1421
+
"state": "123456",
1422
+
"list": [{
1423
+
"id": "msg1023",
1424
+
"threadId": "trd194"
1425
+
}, {
1426
+
"id": "msg223",
1427
+
"threadId": "trd114"
1428
+
},
1429
+
...
1430
+
],
1431
+
"notFound": []
1432
+
}, "t1" ],
1433
+
[ "Thread/get", {
1434
+
"accountId": "A1",
1435
+
"state": "123456",
1436
+
"list": [{
1437
+
"id": "trd194",
1438
+
"emailIds": [ "msg1020", "msg1021", "msg1023" ]
1439
+
}, {
1440
+
"id": "trd114",
1441
+
"emailIds": [ "msg201", "msg223" ]
1442
+
},
1443
+
...
1444
+
],
1445
+
"notFound": []
1446
+
}, "t2" ]]
1447
+
1448
+
To execute the final "Email/get" call, we look through the arguments
1449
+
and find there is one with a "#" prefix. To resolve this, we apply
1450
+
the algorithm:
1451
+
1452
+
1. Find the first response with method call id "t2". The "Thread/
1453
+
get" response fulfils this criterion.
1454
+
1455
+
1456
+
1457
+
1458
+
Jenkins & Newman Standards Track [Page 26]
1459
+
1460
+
RFC 8620 JMAP July 2019
1461
+
1462
+
1463
+
2. "Thread/get" is the name specified in the result reference, so
1464
+
this is fine.
1465
+
1466
+
3. Apply the "path" as a JSON Pointer to the arguments object.
1467
+
Token by token:
1468
+
1469
+
1. "list": get the array of thread objects
1470
+
1471
+
2. "*": for each of the items in the array:
1472
+
1473
+
a. "emailIds": get the array of Email ids
1474
+
1475
+
b. Concatenate these into a single array of all the ids in
1476
+
the result.
1477
+
1478
+
The JMAP server now continues to process the "Email/get" call as
1479
+
though the arguments were:
1480
+
1481
+
{
1482
+
"accountId": "A1",
1483
+
"ids": [ "msg1020", "msg1021", "msg1023", "msg201", "msg223", ... ],
1484
+
"properties": [ "from", "receivedAt", "subject" ]
1485
+
}
1486
+
1487
+
The ResultReference performs a similar role to that of the creation
1488
+
id, in that it allows a chained method call to refer to information
1489
+
not available when the request is generated. However, they are
1490
+
different things and not interchangeable; the only commonality is the
1491
+
octothorpe used to indicate them.
1492
+
1493
+
3.8. Localisation of User-Visible Strings
1494
+
1495
+
If returning a custom string to be displayed to the user, for
1496
+
example, an error message, the server SHOULD use information from the
1497
+
Accept-Language header of the request (as defined in Section 5.3.5 of
1498
+
[RFC7231]) to choose the best available localisation. The Content-
1499
+
Language header of the response (see Section 3.1.3.2 of [RFC7231])
1500
+
SHOULD indicate the language being used for user-visible strings.
1501
+
1502
+
For example, suppose a request was made with the following header:
1503
+
1504
+
Accept-Language: fr-CH, fr;q=0.9, de;q=0.8, en;q=0.7, *;q=0.5
1505
+
1506
+
and a method generated an error to display to the user. The server
1507
+
has translations of the error message in English and German. Looking
1508
+
at the Accept-Language header, the user's preferred language is
1509
+
French. Since we don't have a translation for this, we look at the
1510
+
1511
+
1512
+
1513
+
1514
+
Jenkins & Newman Standards Track [Page 27]
1515
+
1516
+
RFC 8620 JMAP July 2019
1517
+
1518
+
1519
+
next most preferred, which is German. We have a German translation,
1520
+
so the server returns this and indicates the language chosen in a
1521
+
Content-Language header like so:
1522
+
1523
+
Content-Language: de
1524
+
1525
+
3.9. Security
1526
+
1527
+
As always, the server must be strict about data received from the
1528
+
client. Arguments need to be checked for validity; a malicious user
1529
+
could attempt to find an exploit through the API. In case of invalid
1530
+
arguments (unknown/insufficient/wrong type for data, etc.), the
1531
+
method MUST return an "invalidArguments" error and terminate.
1532
+
1533
+
3.10. Concurrency
1534
+
1535
+
Method calls within a single request MUST be executed in order.
1536
+
However, method calls from different concurrent API requests may be
1537
+
interleaved. This means that the data on the server may change
1538
+
between two method calls within a single API request.
1539
+
1540
+
4. The Core/echo Method
1541
+
1542
+
The "Core/echo" method returns exactly the same arguments as it is
1543
+
given. It is useful for testing if you have a valid authenticated
1544
+
connection to a JMAP API endpoint.
1545
+
1546
+
4.1. Example
1547
+
1548
+
Request:
1549
+
1550
+
[[ "Core/echo", {
1551
+
"hello": true,
1552
+
"high": 5
1553
+
}, "b3ff" ]]
1554
+
1555
+
Response:
1556
+
1557
+
[[ "Core/echo", {
1558
+
"hello": true,
1559
+
"high": 5
1560
+
}, "b3ff" ]]
1561
+
1562
+
1563
+
1564
+
1565
+
1566
+
1567
+
1568
+
1569
+
1570
+
Jenkins & Newman Standards Track [Page 28]
1571
+
1572
+
RFC 8620 JMAP July 2019
1573
+
1574
+
1575
+
5. Standard Methods and Naming Convention
1576
+
1577
+
JMAP provides a uniform interface for creating, retrieving, updating,
1578
+
and deleting objects of a particular type. For a "Foo" data type,
1579
+
records of that type would be fetched via a "Foo/get" call and
1580
+
modified via a "Foo/set" call. Delta updates may be fetched via a
1581
+
"Foo/changes" call. These methods all follow a standard format as
1582
+
described below.
1583
+
1584
+
Some types may not have all these methods. Specifications defining
1585
+
types MUST specify which methods are available for the type.
1586
+
1587
+
5.1. /get
1588
+
1589
+
Objects of type Foo are fetched via a call to "Foo/get".
1590
+
1591
+
It takes the following arguments:
1592
+
1593
+
o accountId: "Id"
1594
+
1595
+
The id of the account to use.
1596
+
1597
+
o ids: "Id[]|null"
1598
+
1599
+
The ids of the Foo objects to return. If null, then *all* records
1600
+
of the data type are returned, if this is supported for that data
1601
+
type and the number of records does not exceed the
1602
+
"maxObjectsInGet" limit.
1603
+
1604
+
o properties: "String[]|null"
1605
+
1606
+
If supplied, only the properties listed in the array are returned
1607
+
for each Foo object. If null, all properties of the object are
1608
+
returned. The id property of the object is *always* returned,
1609
+
even if not explicitly requested. If an invalid property is
1610
+
requested, the call MUST be rejected with an "invalidArguments"
1611
+
error.
1612
+
1613
+
The response has the following arguments:
1614
+
1615
+
o accountId: "Id"
1616
+
1617
+
The id of the account used for the call.
1618
+
1619
+
1620
+
1621
+
1622
+
1623
+
1624
+
1625
+
1626
+
Jenkins & Newman Standards Track [Page 29]
1627
+
1628
+
RFC 8620 JMAP July 2019
1629
+
1630
+
1631
+
o state: "String"
1632
+
1633
+
A (preferably short) string representing the state on the server
1634
+
for *all* the data of this type in the account (not just the
1635
+
objects returned in this call). If the data changes, this string
1636
+
MUST change. If the Foo data is unchanged, servers SHOULD return
1637
+
the same state string on subsequent requests for this data type.
1638
+
When a client receives a response with a different state string to
1639
+
a previous call, it MUST either throw away all currently cached
1640
+
objects for the type or call "Foo/changes" to get the exact
1641
+
changes.
1642
+
1643
+
o list: "Foo[]"
1644
+
1645
+
An array of the Foo objects requested. This is the *empty array*
1646
+
if no objects were found or if the "ids" argument passed in was
1647
+
also an empty array. The results MAY be in a different order to
1648
+
the "ids" in the request arguments. If an identical id is
1649
+
included more than once in the request, the server MUST only
1650
+
include it once in either the "list" or the "notFound" argument of
1651
+
the response.
1652
+
1653
+
o notFound: "Id[]"
1654
+
1655
+
This array contains the ids passed to the method for records that
1656
+
do not exist. The array is empty if all requested ids were found
1657
+
or if the "ids" argument passed in was either null or an empty
1658
+
array.
1659
+
1660
+
The following additional error may be returned instead of the "Foo/
1661
+
get" response:
1662
+
1663
+
"requestTooLarge": The number of ids requested by the client exceeds
1664
+
the maximum number the server is willing to process in a single
1665
+
method call.
1666
+
1667
+
5.2. /changes
1668
+
1669
+
When the state of the set of Foo records in an account changes on the
1670
+
server (whether due to creation, updates, or deletion), the "state"
1671
+
property of the "Foo/get" response will change. The "Foo/changes"
1672
+
method allows a client to efficiently update the state of its Foo
1673
+
cache to match the new state on the server. It takes the following
1674
+
arguments:
1675
+
1676
+
o accountId: "Id"
1677
+
1678
+
The id of the account to use.
1679
+
1680
+
1681
+
1682
+
Jenkins & Newman Standards Track [Page 30]
1683
+
1684
+
RFC 8620 JMAP July 2019
1685
+
1686
+
1687
+
o sinceState: "String"
1688
+
1689
+
The current state of the client. This is the string that was
1690
+
returned as the "state" argument in the "Foo/get" response. The
1691
+
server will return the changes that have occurred since this
1692
+
state.
1693
+
1694
+
o maxChanges: "UnsignedInt|null"
1695
+
1696
+
The maximum number of ids to return in the response. The server
1697
+
MAY choose to return fewer than this value but MUST NOT return
1698
+
more. If not given by the client, the server may choose how many
1699
+
to return. If supplied by the client, the value MUST be a
1700
+
positive integer greater than 0. If a value outside of this range
1701
+
is given, the server MUST reject the call with an
1702
+
"invalidArguments" error.
1703
+
1704
+
The response has the following arguments:
1705
+
1706
+
o accountId: "Id"
1707
+
1708
+
The id of the account used for the call.
1709
+
1710
+
o oldState: "String"
1711
+
1712
+
This is the "sinceState" argument echoed back; it's the state from
1713
+
which the server is returning changes.
1714
+
1715
+
o newState: "String"
1716
+
1717
+
This is the state the client will be in after applying the set of
1718
+
changes to the old state.
1719
+
1720
+
o hasMoreChanges: "Boolean"
1721
+
1722
+
If true, the client may call "Foo/changes" again with the
1723
+
"newState" returned to get further updates. If false, "newState"
1724
+
is the current server state.
1725
+
1726
+
o created: "Id[]"
1727
+
1728
+
An array of ids for records that have been created since the old
1729
+
state.
1730
+
1731
+
o updated: "Id[]"
1732
+
1733
+
An array of ids for records that have been updated since the old
1734
+
state.
1735
+
1736
+
1737
+
1738
+
Jenkins & Newman Standards Track [Page 31]
1739
+
1740
+
RFC 8620 JMAP July 2019
1741
+
1742
+
1743
+
o destroyed: "Id[]"
1744
+
1745
+
An array of ids for records that have been destroyed since the old
1746
+
state.
1747
+
1748
+
If a record has been created AND updated since the old state, the
1749
+
server SHOULD just return the id in the "created" list but MAY return
1750
+
it in the "updated" list as well.
1751
+
1752
+
If a record has been updated AND destroyed since the old state, the
1753
+
server SHOULD just return the id in the "destroyed" list but MAY
1754
+
return it in the "updated" list as well.
1755
+
1756
+
If a record has been created AND destroyed since the old state, the
1757
+
server SHOULD remove the id from the response entirely. However, it
1758
+
MAY include it in just the "destroyed" list or in both the
1759
+
"destroyed" and "created" lists.
1760
+
1761
+
If a "maxChanges" is supplied, or set automatically by the server,
1762
+
the server MUST ensure the number of ids returned across "created",
1763
+
"updated", and "destroyed" does not exceed this limit. If there are
1764
+
more changes than this between the client's state and the current
1765
+
server state, the server SHOULD generate an update to take the client
1766
+
to an intermediate state, from which the client can continue to call
1767
+
"Foo/changes" until it is fully up to date. If it is unable to
1768
+
calculate an intermediate state, it MUST return a
1769
+
"cannotCalculateChanges" error response instead.
1770
+
1771
+
When generating intermediate states, the server may choose how to
1772
+
divide up the changes. For many types, it will provide a better user
1773
+
experience to return the more recent changes first, as this is more
1774
+
likely to be what the user is most interested in. The client can
1775
+
then continue to page in the older changes while the user is viewing
1776
+
the newer data. For example, suppose a server went through the
1777
+
following states:
1778
+
1779
+
A -> B -> C -> D -> E
1780
+
1781
+
And a client asks for changes from state "B". The server might first
1782
+
get the ids of records created, updated, or destroyed between states
1783
+
D and E, returning them with:
1784
+
1785
+
state: "B-D-E"
1786
+
hasMoreChanges: true
1787
+
1788
+
1789
+
1790
+
1791
+
1792
+
1793
+
1794
+
Jenkins & Newman Standards Track [Page 32]
1795
+
1796
+
RFC 8620 JMAP July 2019
1797
+
1798
+
1799
+
The client will then ask for the change from state "B-D-E", and the
1800
+
server can return the changes between states C and D, returning:
1801
+
1802
+
state: "B-C-E"
1803
+
hasMoreChanges: true
1804
+
1805
+
Finally, the client will request the changes from "B-C-E", and the
1806
+
server can return the changes between states B and C, returning:
1807
+
1808
+
state: "E"
1809
+
hasMoreChanges: false
1810
+
1811
+
Should the state on the server be modified in the middle of all this
1812
+
(to "F"), the server still does the same, but now when the update to
1813
+
state "E" is returned, it would indicate that it still has more
1814
+
changes for the client to fetch.
1815
+
1816
+
Where multiple changes to a record are split across different
1817
+
intermediate states, the server MUST NOT return a record as created
1818
+
after a response that deems it as updated or destroyed, and it MUST
1819
+
NOT return a record as destroyed before a response that deems it as
1820
+
created or updated. The server may have to coalesce multiple changes
1821
+
to a record to satisfy this requirement.
1822
+
1823
+
The following additional errors may be returned instead of the "Foo/
1824
+
changes" response:
1825
+
1826
+
"cannotCalculateChanges": The server cannot calculate the changes
1827
+
from the state string given by the client. Usually, this is due to
1828
+
the client's state being too old or the server being unable to
1829
+
produce an update to an intermediate state when there are too many
1830
+
updates. The client MUST invalidate its Foo cache.
1831
+
1832
+
Maintaining state to allow calculation of "Foo/changes" can be
1833
+
expensive for the server, but always returning
1834
+
"cannotCalculateChanges" severely increases network traffic and
1835
+
resource usage for the client. To allow efficient sync, servers
1836
+
SHOULD be able to calculate changes from any state string that was
1837
+
given to a client within the last 30 days (but of course may support
1838
+
calculating updates from states older than this).
1839
+
1840
+
1841
+
1842
+
1843
+
1844
+
1845
+
1846
+
1847
+
1848
+
1849
+
1850
+
Jenkins & Newman Standards Track [Page 33]
1851
+
1852
+
RFC 8620 JMAP July 2019
1853
+
1854
+
1855
+
5.3. /set
1856
+
1857
+
Modifying the state of Foo objects on the server is done via the
1858
+
"Foo/set" method. This encompasses creating, updating, and
1859
+
destroying Foo records. This allows the server to sort out ordering
1860
+
and dependencies that may exist if doing multiple operations at once
1861
+
(for example, to ensure there is always a minimum number of a certain
1862
+
record type).
1863
+
1864
+
The "Foo/set" method takes the following arguments:
1865
+
1866
+
o accountId: "Id"
1867
+
1868
+
The id of the account to use.
1869
+
1870
+
o ifInState: "String|null"
1871
+
1872
+
This is a state string as returned by the "Foo/get" method
1873
+
(representing the state of all objects of this type in the
1874
+
account). If supplied, the string must match the current state;
1875
+
otherwise, the method will be aborted and a "stateMismatch" error
1876
+
returned. If null, any changes will be applied to the current
1877
+
state.
1878
+
1879
+
o create: "Id[Foo]|null"
1880
+
1881
+
A map of a *creation id* (a temporary id set by the client) to Foo
1882
+
objects, or null if no objects are to be created.
1883
+
1884
+
The Foo object type definition may define default values for
1885
+
properties. Any such property may be omitted by the client.
1886
+
1887
+
The client MUST omit any properties that may only be set by the
1888
+
server (for example, the "id" property on most object types).
1889
+
1890
+
o update: "Id[PatchObject]|null"
1891
+
1892
+
A map of an id to a Patch object to apply to the current Foo
1893
+
object with that id, or null if no objects are to be updated.
1894
+
1895
+
A *PatchObject* is of type "String[*]" and represents an unordered
1896
+
set of patches. The keys are a path in JSON Pointer format
1897
+
[RFC6901], with an implicit leading "/" (i.e., prefix each key
1898
+
with "/" before applying the JSON Pointer evaluation algorithm).
1899
+
1900
+
All paths MUST also conform to the following restrictions; if
1901
+
there is any violation, the update MUST be rejected with an
1902
+
"invalidPatch" error:
1903
+
1904
+
1905
+
1906
+
Jenkins & Newman Standards Track [Page 34]
1907
+
1908
+
RFC 8620 JMAP July 2019
1909
+
1910
+
1911
+
* The pointer MUST NOT reference inside an array (i.e., you MUST
1912
+
NOT insert/delete from an array; the array MUST be replaced in
1913
+
its entirety instead).
1914
+
1915
+
* All parts prior to the last (i.e., the value after the final
1916
+
slash) MUST already exist on the object being patched.
1917
+
1918
+
* There MUST NOT be two patches in the PatchObject where the
1919
+
pointer of one is the prefix of the pointer of the other, e.g.,
1920
+
"alerts/1/offset" and "alerts".
1921
+
1922
+
The value associated with each pointer determines how to apply
1923
+
that patch:
1924
+
1925
+
* If null, set to the default value if specified for this
1926
+
property; otherwise, remove the property from the patched
1927
+
object. If the key is not present in the parent, this a no-op.
1928
+
1929
+
* Anything else: The value to set for this property (this may be
1930
+
a replacement or addition to the object being patched).
1931
+
1932
+
Any server-set properties MAY be included in the patch if their
1933
+
value is identical to the current server value (before applying
1934
+
the patches to the object). Otherwise, the update MUST be
1935
+
rejected with an "invalidProperties" SetError.
1936
+
1937
+
This patch definition is designed such that an entire Foo object
1938
+
is also a valid PatchObject. The client may choose to optimise
1939
+
network usage by just sending the diff or may send the whole
1940
+
object; the server processes it the same either way.
1941
+
1942
+
o destroy: "Id[]|null"
1943
+
1944
+
A list of ids for Foo objects to permanently delete, or null if no
1945
+
objects are to be destroyed.
1946
+
1947
+
Each creation, modification, or destruction of an object is
1948
+
considered an atomic unit. It is permissible for the server to
1949
+
commit changes to some objects but not others; however, it MUST NOT
1950
+
only commit part of an update to a single record (e.g., update a
1951
+
"name" property but not a "count" property, if both are supplied in
1952
+
the update object).
1953
+
1954
+
The final state MUST be valid after the "Foo/set" is finished;
1955
+
however, the server may have to transition through invalid
1956
+
intermediate states (not exposed to the client) while processing the
1957
+
individual create/update/destroy requests. For example, suppose
1958
+
there is a "name" property that must be unique. A single method call
1959
+
1960
+
1961
+
1962
+
Jenkins & Newman Standards Track [Page 35]
1963
+
1964
+
RFC 8620 JMAP July 2019
1965
+
1966
+
1967
+
could rename an object A => B and simultaneously rename another
1968
+
object B => A. If the final state is valid, this is allowed.
1969
+
Otherwise, each creation, modification, or destruction of an object
1970
+
should be processed sequentially and accepted/rejected based on the
1971
+
current server state.
1972
+
1973
+
If a create, update, or destroy is rejected, the appropriate error
1974
+
MUST be added to the notCreated/notUpdated/notDestroyed property of
1975
+
the response, and the server MUST continue to the next create/update/
1976
+
destroy. It does not terminate the method.
1977
+
1978
+
If an id given cannot be found, the update or destroy MUST be
1979
+
rejected with a "notFound" set error.
1980
+
1981
+
The server MAY skip an update (rejecting it with a "willDestroy"
1982
+
SetError) if that object is destroyed in the same /set request.
1983
+
1984
+
Some records may hold references to other records (foreign keys).
1985
+
That reference may be set (via create or update) in the same request
1986
+
as the referenced record is created. To do this, the client refers
1987
+
to the new record using its creation id prefixed with a "#". The
1988
+
order of the method calls in the request by the client MUST be such
1989
+
that the record being referenced is created in the same or an earlier
1990
+
call. Thus, the server never has to look ahead. Instead, while
1991
+
processing a request, the server MUST keep a simple map for the
1992
+
duration of the request of creation id to record id for each newly
1993
+
created record, so it can substitute in the correct value if
1994
+
necessary in later method calls. In the case of records with
1995
+
references to the same type, the server MUST order the creates and
1996
+
updates within a single method call so that creates happen before
1997
+
their creation ids are referenced by another create/update/destroy in
1998
+
the same call.
1999
+
2000
+
Creation ids are not scoped by type but are a single map for all
2001
+
types. A client SHOULD NOT reuse a creation id anywhere in the same
2002
+
API request. If a creation id is reused, the server MUST map the
2003
+
creation id to the most recently created item with that id. To allow
2004
+
easy proxying of API requests, an initial set of creation id to real
2005
+
id values may be passed with a request (see "The Request Object",
2006
+
Section 3.3) and the final state of the map passed out with the
2007
+
response (see "The Response Object", Section 3.4).
2008
+
2009
+
The response has the following arguments:
2010
+
2011
+
o accountId: "Id"
2012
+
2013
+
The id of the account used for the call.
2014
+
2015
+
2016
+
2017
+
2018
+
Jenkins & Newman Standards Track [Page 36]
2019
+
2020
+
RFC 8620 JMAP July 2019
2021
+
2022
+
2023
+
o oldState: "String|null"
2024
+
2025
+
The state string that would have been returned by "Foo/get" before
2026
+
making the requested changes, or null if the server doesn't know
2027
+
what the previous state string was.
2028
+
2029
+
o newState: "String"
2030
+
2031
+
The state string that will now be returned by "Foo/get".
2032
+
2033
+
o created: "Id[Foo]|null"
2034
+
2035
+
A map of the creation id to an object containing any properties of
2036
+
the created Foo object that were not sent by the client. This
2037
+
includes all server-set properties (such as the "id" in most
2038
+
object types) and any properties that were omitted by the client
2039
+
and thus set to a default by the server.
2040
+
2041
+
This argument is null if no Foo objects were successfully created.
2042
+
2043
+
o updated: "Id[Foo|null]|null"
2044
+
2045
+
The keys in this map are the ids of all Foos that were
2046
+
successfully updated.
2047
+
2048
+
The value for each id is a Foo object containing any property that
2049
+
changed in a way *not* explicitly requested by the PatchObject
2050
+
sent to the server, or null if none. This lets the client know of
2051
+
any changes to server-set or computed properties.
2052
+
2053
+
This argument is null if no Foo objects were successfully updated.
2054
+
2055
+
o destroyed: "Id[]|null"
2056
+
2057
+
A list of Foo ids for records that were successfully destroyed, or
2058
+
null if none.
2059
+
2060
+
o notCreated: "Id[SetError]|null"
2061
+
2062
+
A map of the creation id to a SetError object for each record that
2063
+
failed to be created, or null if all successful.
2064
+
2065
+
o notUpdated: "Id[SetError]|null"
2066
+
2067
+
A map of the Foo id to a SetError object for each record that
2068
+
failed to be updated, or null if all successful.
2069
+
2070
+
2071
+
2072
+
2073
+
2074
+
Jenkins & Newman Standards Track [Page 37]
2075
+
2076
+
RFC 8620 JMAP July 2019
2077
+
2078
+
2079
+
o notDestroyed: "Id[SetError]|null"
2080
+
2081
+
A map of the Foo id to a SetError object for each record that
2082
+
failed to be destroyed, or null if all successful.
2083
+
2084
+
A *SetError* object has the following properties:
2085
+
2086
+
o type: "String"
2087
+
2088
+
The type of error.
2089
+
2090
+
o description: "String|null"
2091
+
2092
+
A description of the error to help with debugging that includes an
2093
+
explanation of what the problem was. This is a non-localised
2094
+
string and is not intended to be shown directly to end users.
2095
+
2096
+
The following SetError types are defined and may be returned for set
2097
+
operations on any record type where appropriate:
2098
+
2099
+
o "forbidden": (create; update; destroy). The create/update/destroy
2100
+
would violate an ACL or other permissions policy.
2101
+
2102
+
o "overQuota": (create; update). The create would exceed a server-
2103
+
defined limit on the number or total size of objects of this type.
2104
+
2105
+
o "tooLarge": (create; update). The create/update would result in
2106
+
an object that exceeds a server-defined limit for the maximum size
2107
+
of a single object of this type.
2108
+
2109
+
o "rateLimit": (create). Too many objects of this type have been
2110
+
created recently, and a server-defined rate limit has been
2111
+
reached. It may work if tried again later.
2112
+
2113
+
o "notFound": (update; destroy). The id given to update/destroy
2114
+
cannot be found.
2115
+
2116
+
o "invalidPatch": (update). The PatchObject given to update the
2117
+
record was not a valid patch (see the patch description).
2118
+
2119
+
o "willDestroy": (update). The client requested that an object be
2120
+
both updated and destroyed in the same /set request, and the
2121
+
server has decided to therefore ignore the update.
2122
+
2123
+
2124
+
2125
+
2126
+
2127
+
2128
+
2129
+
2130
+
Jenkins & Newman Standards Track [Page 38]
2131
+
2132
+
RFC 8620 JMAP July 2019
2133
+
2134
+
2135
+
o "invalidProperties": (create; update). The record given is
2136
+
invalid in some way. For example:
2137
+
2138
+
* It contains properties that are invalid according to the type
2139
+
specification of this record type.
2140
+
2141
+
* It contains a property that may only be set by the server
2142
+
(e.g., "id") and is different to the current value. Note, to
2143
+
allow clients to pass whole objects back, it is not an error to
2144
+
include a server-set property in an update as long as the value
2145
+
is identical to the current value on the server.
2146
+
2147
+
* There is a reference to another record (foreign key), and the
2148
+
given id does not correspond to a valid record.
2149
+
2150
+
The SetError object SHOULD also have a property called
2151
+
"properties" of type "String[]" that lists *all* the properties
2152
+
that were invalid.
2153
+
2154
+
Individual methods MAY specify more specific errors for certain
2155
+
conditions that would otherwise result in an invalidProperties
2156
+
error. If the condition of one of these is met, it MUST be
2157
+
returned instead of the invalidProperties error.
2158
+
2159
+
o "singleton": (create; destroy). This is a singleton type, so you
2160
+
cannot create another one or destroy the existing one.
2161
+
2162
+
Other possible SetError types MAY be given in specific method
2163
+
descriptions. Other properties MAY also be present on the SetError
2164
+
object, as described in the relevant methods.
2165
+
2166
+
The following additional errors may be returned instead of the "Foo/
2167
+
set" response:
2168
+
2169
+
"requestTooLarge": The total number of objects to create, update, or
2170
+
destroy exceeds the maximum number the server is willing to process
2171
+
in a single method call.
2172
+
2173
+
"stateMismatch": An "ifInState" argument was supplied, and it does
2174
+
not match the current state.
2175
+
2176
+
2177
+
2178
+
2179
+
2180
+
2181
+
2182
+
2183
+
2184
+
2185
+
2186
+
Jenkins & Newman Standards Track [Page 39]
2187
+
2188
+
RFC 8620 JMAP July 2019
2189
+
2190
+
2191
+
5.4. /copy
2192
+
2193
+
The only way to move Foo records *between* two different accounts is
2194
+
to copy them using the "Foo/copy" method; once the copy has
2195
+
succeeded, delete the original. The "onSuccessDestroyOriginal"
2196
+
argument allows you to try to do this in one method call; however,
2197
+
note that the two different actions are not atomic, so it is possible
2198
+
for the copy to succeed but the original not to be destroyed for some
2199
+
reason.
2200
+
2201
+
The copy is conceptually in three phases:
2202
+
2203
+
1. Reading the current values from the "from" account.
2204
+
2205
+
2. Writing the new copies to the other account.
2206
+
2207
+
3. Destroying the originals in the "from" account, if requested.
2208
+
2209
+
Data may change in between phases due to concurrent requests.
2210
+
2211
+
The "Foo/copy" method takes the following arguments:
2212
+
2213
+
o fromAccountId: "Id"
2214
+
2215
+
The id of the account to copy records from.
2216
+
2217
+
o ifFromInState: "String|null"
2218
+
2219
+
This is a state string as returned by the "Foo/get" method. If
2220
+
supplied, the string must match the current state of the account
2221
+
referenced by the fromAccountId when reading the data to be
2222
+
copied; otherwise, the method will be aborted and a
2223
+
"stateMismatch" error returned. If null, the data will be read
2224
+
from the current state.
2225
+
2226
+
o accountId: "Id"
2227
+
2228
+
The id of the account to copy records to. This MUST be different
2229
+
to the "fromAccountId".
2230
+
2231
+
o ifInState: "String|null"
2232
+
2233
+
This is a state string as returned by the "Foo/get" method. If
2234
+
supplied, the string must match the current state of the account
2235
+
referenced by the accountId; otherwise, the method will be aborted
2236
+
and a "stateMismatch" error returned. If null, any changes will
2237
+
be applied to the current state.
2238
+
2239
+
2240
+
2241
+
2242
+
Jenkins & Newman Standards Track [Page 40]
2243
+
2244
+
RFC 8620 JMAP July 2019
2245
+
2246
+
2247
+
o create: "Id[Foo]"
2248
+
2249
+
A map of the *creation id* to a Foo object. The Foo object MUST
2250
+
contain an "id" property, which is the id (in the fromAccount) of
2251
+
the record to be copied. When creating the copy, any other
2252
+
properties included are used instead of the current value for that
2253
+
property on the original.
2254
+
2255
+
o onSuccessDestroyOriginal: "Boolean" (default: false)
2256
+
2257
+
If true, an attempt will be made to destroy the original records
2258
+
that were successfully copied: after emitting the "Foo/copy"
2259
+
response, but before processing the next method, the server MUST
2260
+
make a single call to "Foo/set" to destroy the original of each
2261
+
successfully copied record; the output of this is added to the
2262
+
responses as normal, to be returned to the client.
2263
+
2264
+
o destroyFromIfInState: "String|null"
2265
+
2266
+
This argument is passed on as the "ifInState" argument to the
2267
+
implicit "Foo/set" call, if made at the end of this request to
2268
+
destroy the originals that were successfully copied.
2269
+
2270
+
Each record copy is considered an atomic unit that may succeed or
2271
+
fail individually.
2272
+
2273
+
The response has the following arguments:
2274
+
2275
+
o fromAccountId: "Id"
2276
+
2277
+
The id of the account records were copied from.
2278
+
2279
+
o accountId: "Id"
2280
+
2281
+
The id of the account records were copied to.
2282
+
2283
+
o oldState: "String|null"
2284
+
2285
+
The state string that would have been returned by "Foo/get" on the
2286
+
account records that were copied to before making the requested
2287
+
changes, or null if the server doesn't know what the previous
2288
+
state string was.
2289
+
2290
+
o newState: "String"
2291
+
2292
+
The state string that will now be returned by "Foo/get" on the
2293
+
account records were copied to.
2294
+
2295
+
2296
+
2297
+
2298
+
Jenkins & Newman Standards Track [Page 41]
2299
+
2300
+
RFC 8620 JMAP July 2019
2301
+
2302
+
2303
+
o created: "Id[Foo]|null"
2304
+
2305
+
A map of the creation id to an object containing any properties of
2306
+
the copied Foo object that are set by the server (such as the "id"
2307
+
in most object types; note, the id is likely to be different to
2308
+
the id of the object in the account it was copied from).
2309
+
2310
+
This argument is null if no Foo objects were successfully copied.
2311
+
2312
+
o notCreated: "Id[SetError]|null"
2313
+
2314
+
A map of the creation id to a SetError object for each record that
2315
+
failed to be copied, or null if none.
2316
+
2317
+
The SetError may be any of the standard set errors returned for a
2318
+
create or update. In addition, the following SetError is defined:
2319
+
2320
+
"alreadyExists": The server forbids duplicates, and the record
2321
+
already exists in the target account. An "existingId" property of
2322
+
type "Id" MUST be included on the SetError object with the id of the
2323
+
existing record.
2324
+
2325
+
The following additional errors may be returned instead of the "Foo/
2326
+
copy" response:
2327
+
2328
+
"fromAccountNotFound": The "fromAccountId" does not correspond to a
2329
+
valid account.
2330
+
2331
+
"fromAccountNotSupportedByMethod": The "fromAccountId" given
2332
+
corresponds to a valid account, but the account does not support this
2333
+
data type.
2334
+
2335
+
"stateMismatch": An "ifInState" argument was supplied and it does not
2336
+
match the current state, or an "ifFromInState" argument was supplied
2337
+
and it does not match the current state in the from account.
2338
+
2339
+
5.5. /query
2340
+
2341
+
For data sets where the total amount of data is expected to be very
2342
+
small, clients can just fetch the complete set of data and then do
2343
+
any sorting/filtering locally. However, for large data sets (e.g.,
2344
+
multi-gigabyte mailboxes), the client needs to be able to
2345
+
search/sort/window the data type on the server.
2346
+
2347
+
A query on the set of Foos in an account is made by calling "Foo/
2348
+
query". This takes a number of arguments to determine which records
2349
+
to include, how they should be sorted, and which part of the result
2350
+
2351
+
2352
+
2353
+
2354
+
Jenkins & Newman Standards Track [Page 42]
2355
+
2356
+
RFC 8620 JMAP July 2019
2357
+
2358
+
2359
+
should be returned (the full list may be *very* long). The result is
2360
+
returned as a list of Foo ids.
2361
+
2362
+
A call to "Foo/query" takes the following arguments:
2363
+
2364
+
o accountId: "Id"
2365
+
2366
+
The id of the account to use.
2367
+
2368
+
o filter: "FilterOperator|FilterCondition|null"
2369
+
2370
+
Determines the set of Foos returned in the results. If null, all
2371
+
objects in the account of this type are included in the results.
2372
+
A *FilterOperator* object has the following properties:
2373
+
2374
+
* operator: "String"
2375
+
2376
+
This MUST be one of the following strings:
2377
+
2378
+
+ "AND": All of the conditions must match for the filter to
2379
+
match.
2380
+
2381
+
+ "OR": At least one of the conditions must match for the
2382
+
filter to match.
2383
+
2384
+
+ "NOT": None of the conditions must match for the filter to
2385
+
match.
2386
+
2387
+
* conditions: "(FilterOperator|FilterCondition)[]"
2388
+
2389
+
The conditions to evaluate against each record.
2390
+
2391
+
A *FilterCondition* is an "object" whose allowed properties and
2392
+
semantics depend on the data type and is defined in the /query
2393
+
method specification for that type. It MUST NOT have an
2394
+
"operator" property.
2395
+
2396
+
o sort: "Comparator[]|null"
2397
+
2398
+
Lists the names of properties to compare between two Foo records,
2399
+
and how to compare them, to determine which comes first in the
2400
+
sort. If two Foo records have an identical value for the first
2401
+
comparator, the next comparator will be considered, and so on. If
2402
+
all comparators are the same (this includes the case where an
2403
+
empty array or null is given as the "sort" argument), the sort
2404
+
order is server dependent, but it MUST be stable between calls to
2405
+
"Foo/query". A *Comparator* has the following properties:
2406
+
2407
+
2408
+
2409
+
2410
+
Jenkins & Newman Standards Track [Page 43]
2411
+
2412
+
RFC 8620 JMAP July 2019
2413
+
2414
+
2415
+
* property: "String"
2416
+
2417
+
The name of the property on the Foo objects to compare.
2418
+
2419
+
* isAscending: "Boolean" (optional; default: true)
2420
+
2421
+
If true, sort in ascending order. If false, reverse the
2422
+
comparator's results to sort in descending order.
2423
+
2424
+
* collation: "String" (optional; default is server-dependent)
2425
+
2426
+
The identifier, as registered in the collation registry defined
2427
+
in [RFC4790], for the algorithm to use when comparing the order
2428
+
of strings. The algorithms the server supports are advertised
2429
+
in the capabilities object returned with the Session object
2430
+
(see Section 2).
2431
+
2432
+
If omitted, the default algorithm is server dependent, but:
2433
+
2434
+
1. It MUST be unicode-aware.
2435
+
2436
+
2. It MAY be selected based on an Accept-Language header in
2437
+
the request (as defined in [RFC7231], Section 5.3.5) or
2438
+
out-of-band information about the user's language/locale.
2439
+
2440
+
3. It SHOULD be case insensitive where such a concept makes
2441
+
sense for a language/locale. Where the user's language is
2442
+
unknown, it is RECOMMENDED to follow the advice in
2443
+
Section 5.2.3 of [RFC8264].
2444
+
2445
+
The "i;unicode-casemap" collation [RFC5051] and the Unicode
2446
+
Collation Algorithm (<http://www.unicode.org/reports/tr10/>)
2447
+
are two examples that fulfil these criterion and provide
2448
+
reasonable behaviour for a large number of languages.
2449
+
2450
+
When the property being compared is not a string, the
2451
+
"collation" property is ignored, and the following comparison
2452
+
rules apply based on the type. In ascending order:
2453
+
2454
+
+ "Boolean": false comes before true.
2455
+
2456
+
+ "Number": A lower number comes before a higher number.
2457
+
2458
+
+ "Date"/"UTCDate": The earlier date comes first.
2459
+
2460
+
The Comparator object may also have additional properties as
2461
+
required for specific sort operations defined in a type's /query
2462
+
method.
2463
+
2464
+
2465
+
2466
+
Jenkins & Newman Standards Track [Page 44]
2467
+
2468
+
RFC 8620 JMAP July 2019
2469
+
2470
+
2471
+
o position: "Int" (default: 0)
2472
+
2473
+
The zero-based index of the first id in the full list of results
2474
+
to return.
2475
+
2476
+
If a negative value is given, it is an offset from the end of the
2477
+
list. Specifically, the negative value MUST be added to the total
2478
+
number of results given the filter, and if still negative, it's
2479
+
clamped to "0". This is now the zero-based index of the first id
2480
+
to return.
2481
+
2482
+
If the index is greater than or equal to the total number of
2483
+
objects in the results list, then the "ids" array in the response
2484
+
will be empty, but this is not an error.
2485
+
2486
+
o anchor: "Id|null"
2487
+
2488
+
A Foo id. If supplied, the "position" argument is ignored. The
2489
+
index of this id in the results will be used in combination with
2490
+
the "anchorOffset" argument to determine the index of the first
2491
+
result to return (see below for more details).
2492
+
2493
+
o anchorOffset: "Int" (default: 0)
2494
+
2495
+
The index of the first result to return relative to the index of
2496
+
the anchor, if an anchor is given. This MAY be negative. For
2497
+
example, "-1" means the Foo immediately preceding the anchor is
2498
+
the first result in the list returned (see below for more
2499
+
details).
2500
+
2501
+
o limit: "UnsignedInt|null"
2502
+
2503
+
The maximum number of results to return. If null, no limit
2504
+
presumed. The server MAY choose to enforce a maximum "limit"
2505
+
argument. In this case, if a greater value is given (or if it is
2506
+
null), the limit is clamped to the maximum; the new limit is
2507
+
returned with the response so the client is aware. If a negative
2508
+
value is given, the call MUST be rejected with an
2509
+
"invalidArguments" error.
2510
+
2511
+
o calculateTotal: "Boolean" (default: false)
2512
+
2513
+
Does the client wish to know the total number of results in the
2514
+
query? This may be slow and expensive for servers to calculate,
2515
+
particularly with complex filters, so clients should take care to
2516
+
only request the total when needed.
2517
+
2518
+
2519
+
2520
+
2521
+
2522
+
Jenkins & Newman Standards Track [Page 45]
2523
+
2524
+
RFC 8620 JMAP July 2019
2525
+
2526
+
2527
+
If an "anchor" argument is given, the anchor is looked for in the
2528
+
results after filtering and sorting. If found, the "anchorOffset" is
2529
+
then added to its index. If the resulting index is now negative, it
2530
+
is clamped to 0. This index is now used exactly as though it were
2531
+
supplied as the "position" argument. If the anchor is not found, the
2532
+
call is rejected with an "anchorNotFound" error.
2533
+
2534
+
If an "anchor" is specified, any position argument supplied by the
2535
+
client MUST be ignored. If no "anchor" is supplied, any
2536
+
"anchorOffset" argument MUST be ignored.
2537
+
2538
+
A client can use "anchor" instead of "position" to find the index of
2539
+
an id within a large set of results.
2540
+
2541
+
The response has the following arguments:
2542
+
2543
+
o accountId: "Id"
2544
+
2545
+
The id of the account used for the call.
2546
+
2547
+
o queryState: "String"
2548
+
2549
+
A string encoding the current state of the query on the server.
2550
+
This string MUST change if the results of the query (i.e., the
2551
+
matching ids and their sort order) have changed. The queryState
2552
+
string MAY change if something has changed on the server, which
2553
+
means the results may have changed but the server doesn't know for
2554
+
sure.
2555
+
2556
+
The queryState string only represents the ordered list of ids that
2557
+
match the particular query (including its sort/filter). There is
2558
+
no requirement for it to change if a property on an object
2559
+
matching the query changes but the query results are unaffected
2560
+
(indeed, it is more efficient if the queryState string does not
2561
+
change in this case). The queryState string only has meaning when
2562
+
compared to future responses to a query with the same type/sort/
2563
+
filter or when used with /queryChanges to fetch changes.
2564
+
2565
+
Should a client receive back a response with a different
2566
+
queryState string to a previous call, it MUST either throw away
2567
+
the currently cached query and fetch it again (note, this does not
2568
+
require fetching the records again, just the list of ids) or call
2569
+
"Foo/queryChanges" to get the difference.
2570
+
2571
+
2572
+
2573
+
2574
+
2575
+
2576
+
2577
+
2578
+
Jenkins & Newman Standards Track [Page 46]
2579
+
2580
+
RFC 8620 JMAP July 2019
2581
+
2582
+
2583
+
o canCalculateChanges: "Boolean"
2584
+
2585
+
This is true if the server supports calling "Foo/queryChanges"
2586
+
with these "filter"/"sort" parameters. Note, this does not
2587
+
guarantee that the "Foo/queryChanges" call will succeed, as it may
2588
+
only be possible for a limited time afterwards due to server
2589
+
internal implementation details.
2590
+
2591
+
o position: "UnsignedInt"
2592
+
2593
+
The zero-based index of the first result in the "ids" array within
2594
+
the complete list of query results.
2595
+
2596
+
o ids: "Id[]"
2597
+
2598
+
The list of ids for each Foo in the query results, starting at the
2599
+
index given by the "position" argument of this response and
2600
+
continuing until it hits the end of the results or reaches the
2601
+
"limit" number of ids. If "position" is >= "total", this MUST be
2602
+
the empty list.
2603
+
2604
+
o total: "UnsignedInt" (only if requested)
2605
+
2606
+
The total number of Foos in the results (given the "filter").
2607
+
This argument MUST be omitted if the "calculateTotal" request
2608
+
argument is not true.
2609
+
2610
+
o limit: "UnsignedInt" (if set by the server)
2611
+
2612
+
The limit enforced by the server on the maximum number of results
2613
+
to return. This is only returned if the server set a limit or
2614
+
used a different limit than that given in the request.
2615
+
2616
+
The following additional errors may be returned instead of the "Foo/
2617
+
query" response:
2618
+
2619
+
"anchorNotFound": An anchor argument was supplied, but it cannot be
2620
+
found in the results of the query.
2621
+
2622
+
"unsupportedSort": The "sort" is syntactically valid, but it includes
2623
+
a property the server does not support sorting on or a collation
2624
+
method it does not recognise.
2625
+
2626
+
"unsupportedFilter": The "filter" is syntactically valid, but the
2627
+
server cannot process it. If the filter was the result of a user's
2628
+
search input, the client SHOULD suggest that the user simplify their
2629
+
search.
2630
+
2631
+
2632
+
2633
+
2634
+
Jenkins & Newman Standards Track [Page 47]
2635
+
2636
+
RFC 8620 JMAP July 2019
2637
+
2638
+
2639
+
5.6. /queryChanges
2640
+
2641
+
The "Foo/queryChanges" method allows a client to efficiently update
2642
+
the state of a cached query to match the new state on the server. It
2643
+
takes the following arguments:
2644
+
2645
+
o accountId: "Id"
2646
+
2647
+
The id of the account to use.
2648
+
2649
+
o filter: "FilterOperator|FilterCondition|null"
2650
+
2651
+
The filter argument that was used with "Foo/query".
2652
+
2653
+
o sort: "Comparator[]|null"
2654
+
2655
+
The sort argument that was used with "Foo/query".
2656
+
2657
+
o sinceQueryState: "String"
2658
+
2659
+
The current state of the query in the client. This is the string
2660
+
that was returned as the "queryState" argument in the "Foo/query"
2661
+
response with the same sort/filter. The server will return the
2662
+
changes made to the query since this state.
2663
+
2664
+
o maxChanges: "UnsignedInt|null"
2665
+
2666
+
The maximum number of changes to return in the response. See
2667
+
error descriptions below for more details.
2668
+
2669
+
o upToId: "Id|null"
2670
+
2671
+
The last (highest-index) id the client currently has cached from
2672
+
the query results. When there are a large number of results, in a
2673
+
common case, the client may have only downloaded and cached a
2674
+
small subset from the beginning of the results. If the sort and
2675
+
filter are both only on immutable properties, this allows the
2676
+
server to omit changes after this point in the results, which can
2677
+
significantly increase efficiency. If they are not immutable,
2678
+
this argument is ignored.
2679
+
2680
+
o calculateTotal: "Boolean" (default: false)
2681
+
2682
+
Does the client wish to know the total number of results now in
2683
+
the query? This may be slow and expensive for servers to
2684
+
calculate, particularly with complex filters, so clients should
2685
+
take care to only request the total when needed.
2686
+
2687
+
2688
+
2689
+
2690
+
Jenkins & Newman Standards Track [Page 48]
2691
+
2692
+
RFC 8620 JMAP July 2019
2693
+
2694
+
2695
+
The response has the following arguments:
2696
+
2697
+
o accountId: "Id"
2698
+
2699
+
The id of the account used for the call.
2700
+
2701
+
o oldQueryState: "String"
2702
+
2703
+
This is the "sinceQueryState" argument echoed back; that is, the
2704
+
state from which the server is returning changes.
2705
+
2706
+
o newQueryState: "String"
2707
+
2708
+
This is the state the query will be in after applying the set of
2709
+
changes to the old state.
2710
+
2711
+
o total: "UnsignedInt" (only if requested)
2712
+
2713
+
The total number of Foos in the results (given the "filter").
2714
+
This argument MUST be omitted if the "calculateTotal" request
2715
+
argument is not true.
2716
+
2717
+
o removed: "Id[]"
2718
+
2719
+
The "id" for every Foo that was in the query results in the old
2720
+
state and that is not in the results in the new state.
2721
+
2722
+
If the server cannot calculate this exactly, the server MAY return
2723
+
the ids of extra Foos in addition that may have been in the old
2724
+
results but are not in the new results.
2725
+
2726
+
If the sort and filter are both only on immutable properties and
2727
+
an "upToId" is supplied and exists in the results, any ids that
2728
+
were removed but have a higher index than "upToId" SHOULD be
2729
+
omitted.
2730
+
2731
+
If the "filter" or "sort" includes a mutable property, the server
2732
+
MUST include all Foos in the current results for which this
2733
+
property may have changed. The position of these may have moved
2734
+
in the results, so they must be reinserted by the client to ensure
2735
+
its query cache is correct.
2736
+
2737
+
2738
+
2739
+
2740
+
2741
+
2742
+
2743
+
2744
+
2745
+
2746
+
Jenkins & Newman Standards Track [Page 49]
2747
+
2748
+
RFC 8620 JMAP July 2019
2749
+
2750
+
2751
+
o added: "AddedItem[]"
2752
+
2753
+
The id and index in the query results (in the new state) for every
2754
+
Foo that has been added to the results since the old state AND
2755
+
every Foo in the current results that was included in the
2756
+
"removed" array (due to a filter or sort based upon a mutable
2757
+
property).
2758
+
2759
+
If the sort and filter are both only on immutable properties and
2760
+
an "upToId" is supplied and exists in the results, any ids that
2761
+
were added but have a higher index than "upToId" SHOULD be
2762
+
omitted.
2763
+
2764
+
The array MUST be sorted in order of index, with the lowest index
2765
+
first.
2766
+
2767
+
An *AddedItem* object has the following properties:
2768
+
2769
+
* id: "Id"
2770
+
2771
+
* index: "UnsignedInt"
2772
+
2773
+
The result of this is that if the client has a cached sparse array of
2774
+
Foo ids corresponding to the results in the old state, then:
2775
+
2776
+
fooIds = [ "id1", "id2", null, null, "id3", "id4", null, null, null ]
2777
+
2778
+
If it *splices out* all ids in the removed array that it has in its
2779
+
cached results, then:
2780
+
2781
+
removed = [ "id2", "id31", ... ];
2782
+
fooIds => [ "id1", null, null, "id3", "id4", null, null, null ]
2783
+
2784
+
and *splices in* (one by one in order, starting with the lowest
2785
+
index) all of the ids in the added array:
2786
+
2787
+
added = [{ id: "id5", index: 0, ... }];
2788
+
fooIds => [ "id5", "id1", null, null, "id3", "id4", null, null, null ]
2789
+
2790
+
and *truncates* or *extends* to the new total length, then the
2791
+
results will now be in the new state.
2792
+
2793
+
Note: splicing in adds the item at the given index, incrementing the
2794
+
index of all items previously at that or a higher index. Splicing
2795
+
out is the inverse, removing the item and decrementing the index of
2796
+
every item after it in the array.
2797
+
2798
+
2799
+
2800
+
2801
+
2802
+
Jenkins & Newman Standards Track [Page 50]
2803
+
2804
+
RFC 8620 JMAP July 2019
2805
+
2806
+
2807
+
The following additional errors may be returned instead of the "Foo/
2808
+
queryChanges" response:
2809
+
2810
+
"tooManyChanges": There are more changes than the client's
2811
+
"maxChanges" argument. Each item in the removed or added array is
2812
+
considered to be one change. The client may retry with higher max
2813
+
changes or invalidate its cache of the query results.
2814
+
2815
+
"cannotCalculateChanges": The server cannot calculate the changes
2816
+
from the queryState string given by the client, usually due to the
2817
+
client's state being too old. The client MUST invalidate its cache
2818
+
of the query results.
2819
+
2820
+
5.7. Examples
2821
+
2822
+
Suppose we have a type *Todo* with the following properties:
2823
+
2824
+
o id: "Id" (immutable; server-set)
2825
+
2826
+
The id of the object.
2827
+
2828
+
o title: "String"
2829
+
2830
+
A brief summary of what is to be done.
2831
+
2832
+
o keywords: "String[Boolean]" (default: {})
2833
+
2834
+
A set of keywords that apply to the Todo. The set is represented
2835
+
as an object, with the keys being the "keywords". The value for
2836
+
each key in the object MUST be true. (This format allows you to
2837
+
update an individual key using patch syntax rather than having to
2838
+
update the whole set of keywords as one, which a "String[]"
2839
+
representation would require.)
2840
+
2841
+
o neuralNetworkTimeEstimation: "Number" (server-set)
2842
+
2843
+
The title and keywords are fed into the server's state-of-the-art
2844
+
neural network to get an estimation of how long this Todo will
2845
+
take, in seconds.
2846
+
2847
+
o subTodoIds: "Id[]|null"
2848
+
2849
+
The ids of a list of other Todos to complete as part of this Todo.
2850
+
2851
+
Suppose also that all the standard methods are defined for this type
2852
+
and the FilterCondition object supports a "hasKeyword" property to
2853
+
match Todos with the given keyword.
2854
+
2855
+
2856
+
2857
+
2858
+
Jenkins & Newman Standards Track [Page 51]
2859
+
2860
+
RFC 8620 JMAP July 2019
2861
+
2862
+
2863
+
A client might want to display the list of Todos with either a
2864
+
"music" keyword or a "video" keyword, so it makes the following
2865
+
method call:
2866
+
2867
+
[[ "Todo/query", {
2868
+
"accountId": "x",
2869
+
"filter": {
2870
+
"operator": "OR",
2871
+
"conditions": [
2872
+
{ "hasKeyword": "music" },
2873
+
{ "hasKeyword": "video" }
2874
+
]
2875
+
},
2876
+
"sort": [{ "property": "title" }],
2877
+
"position": 0,
2878
+
"limit": 10
2879
+
}, "0" ],
2880
+
[ "Todo/get", {
2881
+
"accountId": "x",
2882
+
"#ids": {
2883
+
"resultOf": "0",
2884
+
"name": "Todo/query",
2885
+
"path": "/ids"
2886
+
}
2887
+
}, "1" ]]
2888
+
2889
+
2890
+
2891
+
2892
+
2893
+
2894
+
2895
+
2896
+
2897
+
2898
+
2899
+
2900
+
2901
+
2902
+
2903
+
2904
+
2905
+
2906
+
2907
+
2908
+
2909
+
2910
+
2911
+
2912
+
2913
+
2914
+
Jenkins & Newman Standards Track [Page 52]
2915
+
2916
+
RFC 8620 JMAP July 2019
2917
+
2918
+
2919
+
This would query the server for the set of Todos with a keyword of
2920
+
either "music" or "video", sorted by title, and limited to the first
2921
+
10 results. It fetches the full object for each of these Todos using
2922
+
back-references to reference the result of the query. The response
2923
+
might look something like:
2924
+
2925
+
[[ "Todo/query", {
2926
+
"accountId": "x",
2927
+
"queryState": "y13213",
2928
+
"canCalculateChanges": true,
2929
+
"position": 0,
2930
+
"ids": [ "a", "b", "c", "d", "e", "f", "g", "h", "i", "j" ]
2931
+
}, "0" ],
2932
+
[ "Todo/get", {
2933
+
"accountId": "x",
2934
+
"state": "10324",
2935
+
"list": [{
2936
+
"id": "a",
2937
+
"title": "Practise Piano",
2938
+
"keywords": {
2939
+
"music": true,
2940
+
"beethoven": true,
2941
+
"mozart": true,
2942
+
"liszt": true,
2943
+
"rachmaninov": true
2944
+
},
2945
+
"neuralNetworkTimeEstimation": 3600
2946
+
}, {
2947
+
"id": "b",
2948
+
"title": "Watch Daft Punk music video",
2949
+
"keywords": {
2950
+
"music": true,
2951
+
"video": true,
2952
+
"trance": true
2953
+
},
2954
+
"neuralNetworkTimeEstimation": 18000
2955
+
},
2956
+
...
2957
+
]
2958
+
}, "1" ]]
2959
+
2960
+
2961
+
2962
+
2963
+
2964
+
2965
+
2966
+
2967
+
2968
+
2969
+
2970
+
Jenkins & Newman Standards Track [Page 53]
2971
+
2972
+
RFC 8620 JMAP July 2019
2973
+
2974
+
2975
+
Now, suppose the user adds a keyword "chopin" and removes the keyword
2976
+
"mozart" from the "Practise Piano" task. The client may send the
2977
+
whole object to the server, as this is a valid PatchObject:
2978
+
2979
+
[[ "Todo/set", {
2980
+
"accountId": "x",
2981
+
"ifInState": "10324",
2982
+
"update": {
2983
+
"a": {
2984
+
"id": "a",
2985
+
"title": "Practise Piano",
2986
+
"keywords": {
2987
+
"music": true,
2988
+
"beethoven": true,
2989
+
"chopin": true,
2990
+
"liszt": true,
2991
+
"rachmaninov": true
2992
+
},
2993
+
"neuralNetworkTimeEstimation": 360
2994
+
}
2995
+
}
2996
+
}, "0" ]]
2997
+
2998
+
or it may send a minimal patch:
2999
+
3000
+
[[ "Todo/set", {
3001
+
"accountId": "x",
3002
+
"ifInState": "10324",
3003
+
"update": {
3004
+
"a": {
3005
+
"keywords/chopin": true,
3006
+
"keywords/mozart": null
3007
+
}
3008
+
}
3009
+
}, "0" ]]
3010
+
3011
+
3012
+
3013
+
3014
+
3015
+
3016
+
3017
+
3018
+
3019
+
3020
+
3021
+
3022
+
3023
+
3024
+
3025
+
3026
+
Jenkins & Newman Standards Track [Page 54]
3027
+
3028
+
RFC 8620 JMAP July 2019
3029
+
3030
+
3031
+
The effect is exactly the same on the server in either case, and
3032
+
presuming the server is still in state "10324", it will probably
3033
+
return success:
3034
+
3035
+
[[ "Todo/set", {
3036
+
"accountId": "x",
3037
+
"oldState": "10324",
3038
+
"newState": "10329",
3039
+
"updated": {
3040
+
"a": {
3041
+
"neuralNetworkTimeEstimation": 5400
3042
+
}
3043
+
}
3044
+
}, "0" ]]
3045
+
3046
+
The server changed the "neuralNetworkTimeEstimation" property on the
3047
+
object as part of this change; as this changed in a way *not*
3048
+
explicitly requested by the PatchObject sent to the server, it is
3049
+
returned with the "updated" confirmation.
3050
+
3051
+
Let us now add a sub-Todo to our new "Practise Piano" Todo. In this
3052
+
example, we can see the use of a reference to a creation id to allow
3053
+
us to set a foreign key reference to a record created in the same
3054
+
request:
3055
+
3056
+
[[ "Todo/set", {
3057
+
"accountId": "x",
3058
+
"create": {
3059
+
"k15": {
3060
+
"title": "Warm up with scales"
3061
+
}
3062
+
},
3063
+
"update": {
3064
+
"a": {
3065
+
"subTodoIds": [ "#k15" ]
3066
+
}
3067
+
}
3068
+
}, "0" ]]
3069
+
3070
+
3071
+
3072
+
3073
+
3074
+
3075
+
3076
+
3077
+
3078
+
3079
+
3080
+
3081
+
3082
+
Jenkins & Newman Standards Track [Page 55]
3083
+
3084
+
RFC 8620 JMAP July 2019
3085
+
3086
+
3087
+
Now, suppose another user deleted the "Listen to Daft Punk" Todo.
3088
+
The first user will receive a push notification (see Section 7) with
3089
+
the changed state string for the "Todo" type. Since the new string
3090
+
does not match its current state, it knows it needs to check for
3091
+
updates. It may make a request like:
3092
+
3093
+
[[ "Todo/changes", {
3094
+
"accountId": "x",
3095
+
"sinceState": "10324",
3096
+
"maxChanges": 50
3097
+
}, "0" ],
3098
+
[ "Todo/queryChanges", {
3099
+
"accountId": "x",
3100
+
"filter": {
3101
+
"operator": "OR",
3102
+
"conditions": [
3103
+
{ "hasKeyword": "music" },
3104
+
{ "hasKeyword": "video" }
3105
+
]
3106
+
},
3107
+
"sort": [{ "property": "title" }],
3108
+
"sinceQueryState": "y13213",
3109
+
"maxChanges": 50
3110
+
}, "1" ]]
3111
+
3112
+
and receive in response:
3113
+
3114
+
[[ "Todo/changes", {
3115
+
"accountId": "x",
3116
+
"oldState": "10324",
3117
+
"newState": "871903",
3118
+
"hasMoreChanges": false,
3119
+
"created": [],
3120
+
"updated": [],
3121
+
"destroyed": ["b"]
3122
+
}, "0" ],
3123
+
[ "Todo/queryChanges", {
3124
+
"accountId": "x",
3125
+
"oldQueryState": "y13213",
3126
+
"newQueryState": "y13218",
3127
+
"removed": ["b"],
3128
+
"added": null
3129
+
}, "1" ]]
3130
+
3131
+
3132
+
3133
+
3134
+
3135
+
3136
+
3137
+
3138
+
Jenkins & Newman Standards Track [Page 56]
3139
+
3140
+
RFC 8620 JMAP July 2019
3141
+
3142
+
3143
+
Suppose the user has access to another account "y", for example, a
3144
+
team account shared between multiple users. To move an existing Todo
3145
+
from account "x", the client would call:
3146
+
3147
+
[[ "Todo/copy", {
3148
+
"fromAccountId": "x",
3149
+
"accountId": "y",
3150
+
"create": {
3151
+
"k5122": {
3152
+
"id": "a"
3153
+
}
3154
+
},
3155
+
"onSuccessDestroyOriginal": true
3156
+
}, "0" ]]
3157
+
3158
+
The server successfully copies the Todo to a new account (where it
3159
+
receives a new id) and deletes the original. Due to the implicit
3160
+
call to "Todo/set", there are two responses to the single method
3161
+
call, both with the same method call id:
3162
+
3163
+
[[ "Todo/copy", {
3164
+
"fromAccountId": "x",
3165
+
"accountId": "y",
3166
+
"created": {
3167
+
"k5122": {
3168
+
"id": "DAf97"
3169
+
}
3170
+
},
3171
+
"oldState": "c1d64ecb038c",
3172
+
"newState": "33844835152b"
3173
+
}, "0" ],
3174
+
[ "Todo/set", {
3175
+
"accountId": "x",
3176
+
"oldState": "871903",
3177
+
"newState": "871909",
3178
+
"destroyed": [ "a" ],
3179
+
...
3180
+
}, "0" ]]
3181
+
3182
+
3183
+
3184
+
3185
+
3186
+
3187
+
3188
+
3189
+
3190
+
3191
+
3192
+
3193
+
3194
+
Jenkins & Newman Standards Track [Page 57]
3195
+
3196
+
RFC 8620 JMAP July 2019
3197
+
3198
+
3199
+
5.8. Proxy Considerations
3200
+
3201
+
JMAP has been designed to allow an API endpoint to easily proxy
3202
+
through to one or more JMAP servers. This may be useful for load
3203
+
balancing, augmenting capabilities, or presenting a single endpoint
3204
+
to accounts hosted on different JMAP servers (splitting the request
3205
+
based on each method's "accountId" argument). The proxy need only
3206
+
understand the general structure of a JMAP Request object; it does
3207
+
not need to know anything specifically about the methods and
3208
+
arguments it will pass through to other servers.
3209
+
3210
+
If splitting up the methods in a request to call them on different
3211
+
backend servers, the proxy must do two things to ensure back-
3212
+
references and creation-id references resolve the same as if the
3213
+
entire request were processed on a single server:
3214
+
3215
+
1. It must pass a "createdIds" property with each subrequest. If
3216
+
this is not given by the client, an empty object should be used
3217
+
for the first subrequest. The "createdIds" property of each
3218
+
subresponse should be passed on in the next subrequest.
3219
+
3220
+
2. It must resolve back-references to previous method results that
3221
+
were processed on a different server. This is a relatively
3222
+
simple syntactic substitution, described in Section 3.7.
3223
+
3224
+
When splitting a request based on accountId, proxy implementors do
3225
+
need to be aware of "/copy" methods that copy between accounts. If
3226
+
the accounts are on different servers, the proxy will have to
3227
+
implement this functionality directly.
3228
+
3229
+
6. Binary Data
3230
+
3231
+
Binary data is referenced by a *blobId* in JMAP and uploaded/
3232
+
downloaded separately to the core API. The blobId solely represents
3233
+
the raw bytes of data, not any associated metadata such as a file
3234
+
name or content type. Such metadata is stored alongside the blobId
3235
+
in the object referencing it. The data represented by a blobId is
3236
+
immutable.
3237
+
3238
+
Any blobId that exists within an account may be used when creating/
3239
+
updating another object in that account. For example, an Email type
3240
+
may have a blobId that represents the object in Internet Message
3241
+
Format [RFC5322]. A client could create a new Email object with an
3242
+
attachment and use this blobId, in effect attaching the old message
3243
+
to the new one. Similarly, it could attach any existing attachment
3244
+
of an old message without having to download and upload it again.
3245
+
3246
+
3247
+
3248
+
3249
+
3250
+
Jenkins & Newman Standards Track [Page 58]
3251
+
3252
+
RFC 8620 JMAP July 2019
3253
+
3254
+
3255
+
When the client uses a blobId in a create/update, the server MAY
3256
+
assign a new blobId to refer to the same binary data within the new/
3257
+
updated object. If it does so, it MUST return any properties that
3258
+
contain a changed blobId in the created/updated response, so the
3259
+
client gets the new ids.
3260
+
3261
+
A blob that is not referenced by a JMAP object (e.g., as a message
3262
+
attachment) MAY be deleted by the server to free up resources.
3263
+
Uploads (see below) are initially unreferenced blobs. To ensure
3264
+
interoperability:
3265
+
3266
+
o The server SHOULD use a separate quota for unreferenced blobs to
3267
+
the account's usual quota. In the case of shared accounts, this
3268
+
quota SHOULD be separate per user.
3269
+
3270
+
o This quota SHOULD be at least the maximum total size that a single
3271
+
object can reference on this server. For example, if supporting
3272
+
JMAP Mail, this should be at least the maximum total attachments
3273
+
size for a message.
3274
+
3275
+
o When an upload would take the user over quota, the server MUST
3276
+
delete unreferenced blobs in date order, oldest first, until there
3277
+
is room for the new blob.
3278
+
3279
+
o Except where quota restrictions force early deletion, an
3280
+
unreferenced blob MUST NOT be deleted for at least 1 hour from the
3281
+
time of upload; if reuploaded, the same blobId MAY be returned,
3282
+
but this SHOULD reset the expiry time.
3283
+
3284
+
o A blob MUST NOT be deleted during the method call that removed the
3285
+
last reference, so that a client can issue a create and a destroy
3286
+
that both reference the blob within the same method call.
3287
+
3288
+
6.1. Uploading Binary Data
3289
+
3290
+
There is a single endpoint that handles all file uploads for an
3291
+
account, regardless of what they are to be used for. The Session
3292
+
object (see Section 2) has an "uploadUrl" property in URI Template
3293
+
(level 1) format [RFC6570], which MUST contain a variable called
3294
+
"accountId". The client may use this template in combination with an
3295
+
"accountId" to get the URL of the file upload resource.
3296
+
3297
+
To upload a file, the client submits an authenticated POST request to
3298
+
the file upload resource.
3299
+
3300
+
3301
+
3302
+
3303
+
3304
+
3305
+
3306
+
Jenkins & Newman Standards Track [Page 59]
3307
+
3308
+
RFC 8620 JMAP July 2019
3309
+
3310
+
3311
+
A successful request MUST return a single JSON object with the
3312
+
following properties as the response:
3313
+
3314
+
o accountId: "Id"
3315
+
3316
+
The id of the account used for the call.
3317
+
3318
+
o blobId: "Id"
3319
+
3320
+
The id representing the binary data uploaded. The data for this
3321
+
id is immutable. The id *only* refers to the binary data, not any
3322
+
metadata.
3323
+
3324
+
o type: "String"
3325
+
3326
+
The media type of the file (as specified in [RFC6838],
3327
+
Section 4.2) as set in the Content-Type header of the upload HTTP
3328
+
request.
3329
+
3330
+
o size: "UnsignedInt"
3331
+
3332
+
The size of the file in octets.
3333
+
3334
+
If identical binary content to an existing blob in the account is
3335
+
uploaded, the existing blobId MAY be returned.
3336
+
3337
+
Clients should use the blobId returned in a timely manner. Under
3338
+
rare circumstances, the server may have deleted the blob before the
3339
+
client uses it; the client should keep a reference to the local file
3340
+
so it can upload it again in such a situation.
3341
+
3342
+
When an HTTP error response is returned to the client, the server
3343
+
SHOULD return a JSON "problem details" object as the response body,
3344
+
as per [RFC7807].
3345
+
3346
+
As access controls are often determined by the object holding the
3347
+
reference to a blob, unreferenced blobs MUST only be accessible to
3348
+
the uploader, even in shared accounts.
3349
+
3350
+
6.2. Downloading Binary Data
3351
+
3352
+
The Session object (see Section 2) has a "downloadUrl" property,
3353
+
which is in URI Template (level 1) format [RFC6570]. The URL MUST
3354
+
contain variables called "accountId", "blobId", "type", and "name".
3355
+
3356
+
3357
+
3358
+
3359
+
3360
+
3361
+
3362
+
Jenkins & Newman Standards Track [Page 60]
3363
+
3364
+
RFC 8620 JMAP July 2019
3365
+
3366
+
3367
+
To download a file, the client makes an authenticated GET request to
3368
+
the download URL with the appropriate variables substituted in:
3369
+
3370
+
o "accountId": The id of the account to which the record with the
3371
+
blobId belongs.
3372
+
3373
+
o "blobId": The blobId representing the data of the file to
3374
+
download.
3375
+
3376
+
o "type": The type for the server to set in the "Content-Type"
3377
+
header of the response; the blobId only represents the binary data
3378
+
and does not have a content-type innately associated with it.
3379
+
3380
+
o "name": The name for the file; the server MUST return this as the
3381
+
filename if it sets a "Content-Disposition" header.
3382
+
3383
+
As the data for a particular blobId is immutable, and thus the
3384
+
response in the generated download URL is too, implementors are
3385
+
recommended to set long cache times and use the "immutable" Cache-
3386
+
Control extension [RFC8246] for successful responses, for example,
3387
+
"Cache-Control: private, immutable, max-age=31536000".
3388
+
3389
+
When an HTTP error response is returned to the client, the server
3390
+
SHOULD return a JSON "problem details" object as the response body,
3391
+
as per [RFC7807].
3392
+
3393
+
6.3. Blob/copy
3394
+
3395
+
Binary data may be copied *between* two different accounts using the
3396
+
"Blob/copy" method rather than having to download and then reupload
3397
+
on the client.
3398
+
3399
+
The "Blob/copy" method takes the following arguments:
3400
+
3401
+
o fromAccountId: "Id"
3402
+
3403
+
The id of the account to copy blobs from.
3404
+
3405
+
o accountId: "Id"
3406
+
3407
+
The id of the account to copy blobs to.
3408
+
3409
+
o blobIds: "Id[]"
3410
+
3411
+
A list of ids of blobs to copy to the other account.
3412
+
3413
+
3414
+
3415
+
3416
+
3417
+
3418
+
Jenkins & Newman Standards Track [Page 61]
3419
+
3420
+
RFC 8620 JMAP July 2019
3421
+
3422
+
3423
+
The response has the following arguments:
3424
+
3425
+
o fromAccountId: "Id"
3426
+
3427
+
The id of the account blobs were copied from.
3428
+
3429
+
o accountId: "Id"
3430
+
3431
+
The id of the account blobs were copied to.
3432
+
3433
+
o copied: "Id[Id]|null"
3434
+
3435
+
A map of the blobId in the fromAccount to the id for the blob in
3436
+
the account it was copied to, or null if none were successfully
3437
+
copied.
3438
+
3439
+
o notCopied: "Id[SetError]|null"
3440
+
3441
+
A map of blobId to a SetError object for each blob that failed to
3442
+
be copied, or null if none.
3443
+
3444
+
The SetError may be any of the standard set errors that may be
3445
+
returned for a create, as defined in Section 5.3. In addition, the
3446
+
"notFound" SetError error may be returned if the blobId to be copied
3447
+
cannot be found.
3448
+
3449
+
The following additional method-level error may be returned instead
3450
+
of the "Blob/copy" response:
3451
+
3452
+
"fromAccountNotFound": The "fromAccountId" included with the request
3453
+
does not correspond to a valid account.
3454
+
3455
+
7. Push
3456
+
3457
+
Push notifications allow clients to efficiently update (almost)
3458
+
instantly to stay in sync with data changes on the server. The
3459
+
general model for push is simple and sends minimal data over the push
3460
+
channel: just enough for the client to know whether it needs to
3461
+
resync. The format allows multiple changes to be coalesced into a
3462
+
single push update and the frequency of pushes to be rate limited by
3463
+
the server. It doesn't matter if some push events are dropped before
3464
+
they reach the client; the next time it gets/sets any records of a
3465
+
changed type, it will discover the data has changed and still sync
3466
+
all changes.
3467
+
3468
+
3469
+
3470
+
3471
+
3472
+
3473
+
3474
+
Jenkins & Newman Standards Track [Page 62]
3475
+
3476
+
RFC 8620 JMAP July 2019
3477
+
3478
+
3479
+
There are two different mechanisms by which a client can receive push
3480
+
notifications, to allow for the different environments in which a
3481
+
client may exist. An event source resource (see Section 7.3) allows
3482
+
clients that can hold transport connections open to receive push
3483
+
notifications directly from the JMAP server. This is simple and
3484
+
avoids third parties, but it is often not feasible on constrained
3485
+
platforms such as mobile devices. Alternatively, clients can make
3486
+
use of any push service supported by their environment. A URL for
3487
+
the push service is registered with the JMAP server (see
3488
+
Section 7.2); the server then POSTs each notification to that URL.
3489
+
The push service is then responsible for routing these to the client.
3490
+
3491
+
7.1. The StateChange Object
3492
+
3493
+
When something changes on the server, the server pushes a StateChange
3494
+
object to the client. A *StateChange* object has the following
3495
+
properties:
3496
+
3497
+
o @type: "String"
3498
+
3499
+
This MUST be the string "StateChange".
3500
+
3501
+
o changed: "Id[TypeState]"
3502
+
3503
+
A map of an "account id" to an object encoding the state of data
3504
+
types that have changed for that account since the last
3505
+
StateChange object was pushed, for each of the accounts to which
3506
+
the user has access and for which something has changed.
3507
+
3508
+
A *TypeState* object is a map. The keys are the type name "Foo"
3509
+
(e.g., "Mailbox" or "Email"), and the value is the "state"
3510
+
property that would currently be returned by a call to "Foo/get".
3511
+
3512
+
The client can compare the new state strings with its current
3513
+
values to see whether it has the current data for these types. If
3514
+
not, the changes can then be efficiently fetched in a single
3515
+
standard API request (using the /changes type methods).
3516
+
3517
+
3518
+
3519
+
3520
+
3521
+
3522
+
3523
+
3524
+
3525
+
3526
+
3527
+
3528
+
3529
+
3530
+
Jenkins & Newman Standards Track [Page 63]
3531
+
3532
+
RFC 8620 JMAP July 2019
3533
+
3534
+
3535
+
7.1.1. Example
3536
+
3537
+
In this example, the server has amalgamated a few changes together
3538
+
across two different accounts the user has access to, before pushing
3539
+
the following StateChange object to the client:
3540
+
3541
+
{
3542
+
"@type": "StateChange",
3543
+
"changed": {
3544
+
"a3123": {
3545
+
"Email": "d35ecb040aab",
3546
+
"EmailDelivery": "428d565f2440",
3547
+
"CalendarEvent": "87accfac587a"
3548
+
},
3549
+
"a43461d": {
3550
+
"Mailbox": "0af7a512ce70",
3551
+
"CalendarEvent": "7a4297cecd76"
3552
+
}
3553
+
}
3554
+
}
3555
+
3556
+
The client can compare the state strings with its current state for
3557
+
the Email, CalendarEvent, etc., object types in the appropriate
3558
+
accounts to see if it needs to fetch changes.
3559
+
3560
+
If the client is itself making changes, it may receive a StateChange
3561
+
object while the /set API call is in flight. It can wait until the
3562
+
call completes and then compare if the new state string after the
3563
+
/set is the same as was pushed in the StateChange object; if so, and
3564
+
the old state of the /set response matches the client's previous
3565
+
state, it does not need to waste a request asking for changes it
3566
+
already knows.
3567
+
3568
+
7.2. PushSubscription
3569
+
3570
+
Clients may create a PushSubscription to register a URL with the JMAP
3571
+
server. The JMAP server will then make an HTTP POST request to this
3572
+
URL for each push notification it wishes to send to the client.
3573
+
3574
+
As a push subscription causes the JMAP server to make a number of
3575
+
requests to a previously unknown endpoint, it can be used as a vector
3576
+
for launching a denial-of-service attack. To prevent this, when a
3577
+
subscription is created, the JMAP server immediately sends a
3578
+
PushVerification object to that URL (see Section 7.2.2). The JMAP
3579
+
server MUST NOT make any further requests to the URL until the client
3580
+
receives the push and updates the subscription with the correct
3581
+
verification code.
3582
+
3583
+
3584
+
3585
+
3586
+
Jenkins & Newman Standards Track [Page 64]
3587
+
3588
+
RFC 8620 JMAP July 2019
3589
+
3590
+
3591
+
A *PushSubscription* object has the following properties:
3592
+
3593
+
o id: "Id" (immutable; server-set)
3594
+
3595
+
The id of the push subscription.
3596
+
3597
+
o deviceClientId: "String" (immutable)
3598
+
3599
+
An id that uniquely identifies the client + device it is running
3600
+
on. The purpose of this is to allow clients to identify which
3601
+
PushSubscription objects they created even if they lose their
3602
+
local state, so they can revoke or update them. This string MUST
3603
+
be different on different devices and be different from apps from
3604
+
other vendors. It SHOULD be easy to regenerate and not depend on
3605
+
persisted state. It is RECOMMENDED to use a secure hash of a
3606
+
string that contains:
3607
+
3608
+
1. A unique identifier associated with the device where the JMAP
3609
+
client is running, normally supplied by the device's operating
3610
+
system.
3611
+
3612
+
2. A custom vendor/app id, including a domain controlled by the
3613
+
vendor of the JMAP client.
3614
+
3615
+
To protect the privacy of the user, the deviceClientId id MUST NOT
3616
+
contain an unobfuscated device id.
3617
+
3618
+
o url: "String" (immutable)
3619
+
3620
+
An absolute URL where the JMAP server will POST the data for the
3621
+
push message. This MUST begin with "https://".
3622
+
3623
+
o keys: "Object|null" (immutable)
3624
+
3625
+
Client-generated encryption keys. If supplied, the server MUST
3626
+
use them as specified in [RFC8291] to encrypt all data sent to the
3627
+
push subscription. The object MUST have the following properties:
3628
+
3629
+
* p256dh: "String"
3630
+
3631
+
The P-256 Elliptic Curve Diffie-Hellman (ECDH) public key as
3632
+
described in [RFC8291], encoded in URL-safe base64
3633
+
representation as defined in [RFC4648].
3634
+
3635
+
* auth: "String"
3636
+
3637
+
The authentication secret as described in [RFC8291], encoded in
3638
+
URL-safe base64 representation as defined in [RFC4648].
3639
+
3640
+
3641
+
3642
+
Jenkins & Newman Standards Track [Page 65]
3643
+
3644
+
RFC 8620 JMAP July 2019
3645
+
3646
+
3647
+
o verificationCode: "String|null"
3648
+
3649
+
This MUST be null (or omitted) when the subscription is created.
3650
+
The JMAP server then generates a verification code and sends it in
3651
+
a push message, and the client updates the PushSubscription object
3652
+
with the code; see Section 7.2.2 for details.
3653
+
3654
+
o expires: "UTCDate|null"
3655
+
3656
+
The time this push subscription expires. If specified, the JMAP
3657
+
server MUST NOT make further requests to this resource after this
3658
+
time. It MAY automatically destroy the push subscription at or
3659
+
after this time.
3660
+
3661
+
The server MAY choose to set an expiry if none is given by the
3662
+
client or modify the expiry time given by the client to a shorter
3663
+
duration.
3664
+
3665
+
o types: "String[]|null"
3666
+
3667
+
A list of types the client is interested in (using the same names
3668
+
as the keys in the TypeState object defined in the previous
3669
+
section). A StateChange notification will only be sent if the
3670
+
data for one of these types changes. Other types are omitted from
3671
+
the TypeState object. If null, changes will be pushed for all
3672
+
types.
3673
+
3674
+
The POST request MUST have a content type of "application/json" and
3675
+
contain the UTF-8 JSON-encoded object as the body. The request MUST
3676
+
have a "TTL" header and MAY have "Urgency" and/or "Topic" headers, as
3677
+
specified in Section 5 of [RFC8030]. The JMAP server is expected to
3678
+
understand and handle HTTP status responses in a reasonable manner.
3679
+
A "429" (Too Many Requests) response MUST cause the JMAP server to
3680
+
reduce the frequency of pushes; the JMAP push structure allows
3681
+
multiple changes to be coalesced into a single minimal StateChange
3682
+
object. See the security considerations in Section 8.6 for a
3683
+
discussion of the risks in connecting to unknown servers.
3684
+
3685
+
The JMAP server acts as an application server as defined in
3686
+
[RFC8030]. A client MAY use the rest of [RFC8030] in combination
3687
+
with its own push service to form a complete end-to-end solution, or
3688
+
it MAY rely on alternative mechanisms to ensure the delivery of the
3689
+
pushed data after it leaves the JMAP server.
3690
+
3691
+
The push subscription is tied to the credentials used to authenticate
3692
+
the API request that created it. Should these credentials expire or
3693
+
be revoked, the push subscription MUST be destroyed by the JMAP
3694
+
3695
+
3696
+
3697
+
3698
+
Jenkins & Newman Standards Track [Page 66]
3699
+
3700
+
RFC 8620 JMAP July 2019
3701
+
3702
+
3703
+
server. Only subscriptions created by these credentials are returned
3704
+
when the client fetches existing subscriptions.
3705
+
3706
+
When these credentials have their own expiry (i.e., it is a session
3707
+
with a timeout), the server SHOULD NOT set or bound the expiry time
3708
+
for the push subscription given by the client but MUST expire it when
3709
+
the session expires.
3710
+
3711
+
When these credentials are not time bounded (e.g., Basic
3712
+
authentication [RFC7617]), the server SHOULD set an expiry time for
3713
+
the push subscription if none is given and limit the expiry time if
3714
+
set too far in the future. This maximum expiry time MUST be at least
3715
+
48 hours in the future and SHOULD be at least 7 days in the future.
3716
+
An app running on a mobile device may only be able to refresh the
3717
+
push subscription lifetime when it is in the foreground, so this
3718
+
gives a reasonable time frame to allow this to happen.
3719
+
3720
+
In the case of separate access and refresh credentials, as in Oauth
3721
+
2.0 [RFC6749], the server SHOULD tie the push subscription to the
3722
+
validity of the refresh token rather than the access token and behave
3723
+
according to whether this is time-limited or not.
3724
+
3725
+
When a push subscription is destroyed, the server MUST securely erase
3726
+
the URL and encryption keys from memory and storage as soon as
3727
+
possible.
3728
+
3729
+
7.2.1. PushSubscription/get
3730
+
3731
+
Standard /get method as described in Section 5.1, except it does
3732
+
*not* take or return an "accountId" argument, as push subscriptions
3733
+
are not tied to specific accounts. It also does *not* return a
3734
+
"state" argument. The "ids" argument may be null to fetch all at
3735
+
once.
3736
+
3737
+
The server MUST only return push subscriptions that were created
3738
+
using the same authentication credentials as for this
3739
+
"PushSubscription/get" request.
3740
+
3741
+
As the "url" and "keys" properties may contain data that is private
3742
+
to a particular device, the values for these properties MUST NOT be
3743
+
returned. If the "properties" argument is null or omitted, the
3744
+
server MUST default to all properties excluding these two. If one of
3745
+
them is explicitly requested, the method call MUST be rejected with a
3746
+
"forbidden" error.
3747
+
3748
+
3749
+
3750
+
3751
+
3752
+
3753
+
3754
+
Jenkins & Newman Standards Track [Page 67]
3755
+
3756
+
RFC 8620 JMAP July 2019
3757
+
3758
+
3759
+
7.2.2. PushSubscription/set
3760
+
3761
+
Standard /set method as described in Section 5.3, except it does
3762
+
*not* take or return an "accountId" argument, as push subscriptions
3763
+
are not tied to specific accounts. It also does *not* take an
3764
+
"ifInState" argument or return "oldState" or "newState" arguments.
3765
+
3766
+
The "url" and "keys" properties are immutable; if the client wishes
3767
+
to change these, it must destroy the current push subscription and
3768
+
create a new one.
3769
+
3770
+
When a PushSubscription is created, the server MUST immediately push
3771
+
a *PushVerification* object to the URL. It has the following
3772
+
properties:
3773
+
3774
+
o @type: "String"
3775
+
3776
+
This MUST be the string "PushVerification".
3777
+
3778
+
o pushSubscriptionId: "String"
3779
+
3780
+
The id of the push subscription that was created.
3781
+
3782
+
o verificationCode: "String"
3783
+
3784
+
The verification code to add to the push subscription. This MUST
3785
+
contain sufficient entropy to avoid the client being able to guess
3786
+
the code via brute force.
3787
+
3788
+
The client MUST update the push subscription with the correct
3789
+
verification code before the server makes any further requests to the
3790
+
subscription's URL. Attempts to update the subscription with an
3791
+
invalid verification code MUST be rejected by the server with an
3792
+
"invalidProperties" SetError.
3793
+
3794
+
The client may update the "expires" property to extend (or, less
3795
+
commonly, shorten) the lifetime of a push subscription. The server
3796
+
MAY modify the proposed new expiry time to enforce server-defined
3797
+
limits. Extending the lifetime does not require the subscription to
3798
+
be verified again.
3799
+
3800
+
Clients SHOULD NOT update or destroy a push subscription that they
3801
+
did not create (i.e., has a "deviceClientId" that they do not
3802
+
recognise).
3803
+
3804
+
3805
+
3806
+
3807
+
3808
+
3809
+
3810
+
Jenkins & Newman Standards Track [Page 68]
3811
+
3812
+
RFC 8620 JMAP July 2019
3813
+
3814
+
3815
+
7.2.3. Example
3816
+
3817
+
At "2018-07-06T02:14:29Z", a client with deviceClientId "a889-ffea-
3818
+
910" fetches the set of push subscriptions currently on the server,
3819
+
making an API request with:
3820
+
3821
+
[[ "PushSubscription/get", {
3822
+
"ids": null
3823
+
}, "0" ]]
3824
+
3825
+
Which returns:
3826
+
3827
+
[[ "PushSubscription/get", {
3828
+
"list": [{
3829
+
"id": "e50b2c1d-9553-41a3-b0a7-a7d26b599ee1",
3830
+
"deviceClientId": "b37ff8001ca0",
3831
+
"verificationCode": "b210ef734fe5f439c1ca386421359f7b",
3832
+
"expires": "2018-07-31T00:13:21Z",
3833
+
"types": [ "Todo" ]
3834
+
}, {
3835
+
"id": "f2d0aab5-e976-4e8b-ad4b-b380a5b987e4",
3836
+
"deviceClientId": "X8980fc",
3837
+
"verificationCode": "f3d4618a9ae15c8b7f5582533786d531",
3838
+
"expires": "2018-07-12T05:55:00Z",
3839
+
"types": [ "Mailbox", "Email", "EmailDelivery" ]
3840
+
}],
3841
+
"notFound": []
3842
+
}, "0" ]]
3843
+
3844
+
Since neither of the returned push subscription objects have the
3845
+
client's deviceClientId, it knows it does not have a current push
3846
+
subscription active on the server. So it creates one, sending this
3847
+
request:
3848
+
3849
+
[[ "PushSubscription/set", {
3850
+
"create": {
3851
+
"4f29": {
3852
+
"deviceClientId": "a889-ffea-910",
3853
+
"url": "https://example.com/push/?device=X8980fc&client=12c6d086",
3854
+
"types": null
3855
+
}
3856
+
}
3857
+
}, "0" ]]
3858
+
3859
+
3860
+
3861
+
3862
+
3863
+
3864
+
3865
+
3866
+
Jenkins & Newman Standards Track [Page 69]
3867
+
3868
+
RFC 8620 JMAP July 2019
3869
+
3870
+
3871
+
The server creates the push subscription but limits the expiry time
3872
+
to 7 days in the future, returning this response:
3873
+
3874
+
[[ "PushSubscription/set", {
3875
+
"created": {
3876
+
"4f29": {
3877
+
"id": "P43dcfa4-1dd4-41ef-9156-2c89b3b19c60",
3878
+
"keys": null,
3879
+
"expires": "2018-07-13T02:14:29Z"
3880
+
}
3881
+
}
3882
+
}, "0" ]]
3883
+
3884
+
The server also immediately makes a POST request to
3885
+
"https://example.com/push/?device=X8980fc&client=12c6d086" with the
3886
+
data:
3887
+
3888
+
{
3889
+
"@type": "PushVerification",
3890
+
"pushSubscriptionId": "P43dcfa4-1dd4-41ef-9156-2c89b3b19c60",
3891
+
"verificationCode": "da1f097b11ca17f06424e30bf02bfa67"
3892
+
}
3893
+
3894
+
The client receives this and updates the subscription with the
3895
+
verification code (note there is a potential race condition here; the
3896
+
client MUST be able to handle receiving the push while the request
3897
+
creating the subscription is still in progress):
3898
+
3899
+
[[ "PushSubscription/set", {
3900
+
"update": {
3901
+
"P43dcfa4-1dd4-41ef-9156-2c89b3b19c60": {
3902
+
"verificationCode": "da1f097b11ca17f06424e30bf02bfa67"
3903
+
}
3904
+
}
3905
+
}, "0" ]]
3906
+
3907
+
The server confirms the update was successful and will now make
3908
+
requests to the registered URL when the state changes.
3909
+
3910
+
3911
+
3912
+
3913
+
3914
+
3915
+
3916
+
3917
+
3918
+
3919
+
3920
+
3921
+
3922
+
Jenkins & Newman Standards Track [Page 70]
3923
+
3924
+
RFC 8620 JMAP July 2019
3925
+
3926
+
3927
+
Two days later, the client updates the subscription to extend its
3928
+
lifetime, sending this request:
3929
+
3930
+
[[ "PushSubscription/set", {
3931
+
"update": {
3932
+
"P43dcfa4-1dd4-41ef-9156-2c89b3b19c60": {
3933
+
"expires": "2018-08-13T00:00:00Z"
3934
+
}
3935
+
}
3936
+
}, "0" ]]
3937
+
3938
+
The server extends the expiry time, but only again to its maximum
3939
+
limit of 7 days in the future, returning this response:
3940
+
3941
+
[[ "PushSubscription/set", {
3942
+
"updated": {
3943
+
"P43dcfa4-1dd4-41ef-9156-2c89b3b19c60": {
3944
+
"expires": "2018-07-15T02:22:50Z"
3945
+
}
3946
+
}
3947
+
}, "0" ]]
3948
+
3949
+
7.3. Event Source
3950
+
3951
+
Clients that can hold transport connections open can connect directly
3952
+
to the JMAP server to receive push notifications via a "text/event-
3953
+
stream" resource, as described in [EventSource]. This is a long
3954
+
running HTTP request, where the server can push data to the client by
3955
+
appending data without ending the response.
3956
+
3957
+
When a change occurs in the data on the server, it pushes an event
3958
+
called "state" to any connected clients, with the StateChange object
3959
+
as the data.
3960
+
3961
+
The server SHOULD also send a new event id that encodes the entire
3962
+
server state visible to the user immediately after sending a "state"
3963
+
event. When a new connection is made to the event-source endpoint, a
3964
+
client following the server-sent events specification will send a
3965
+
Last-Event-ID HTTP header field with the last id it saw, which the
3966
+
server can use to work out whether the client has missed some
3967
+
changes. If so, it SHOULD send these changes immediately on
3968
+
connection.
3969
+
3970
+
The Session object (see Section 2) has an "eventSourceUrl" property,
3971
+
which is in URI Template (level 1) format [RFC6570]. The URL MUST
3972
+
contain variables called "types", "closeafter", and "ping".
3973
+
3974
+
3975
+
3976
+
3977
+
3978
+
Jenkins & Newman Standards Track [Page 71]
3979
+
3980
+
RFC 8620 JMAP July 2019
3981
+
3982
+
3983
+
To connect to the resource, the client makes an authenticated GET
3984
+
request to the event-source URL with the appropriate variables
3985
+
substituted in:
3986
+
3987
+
o "types": This MUST be either:
3988
+
3989
+
* A comma-separated list of type names, e.g.,
3990
+
"Email,CalendarEvent". The server MUST only push changes for
3991
+
the types in this list.
3992
+
3993
+
* The single character: "*". Changes to all types are pushed.
3994
+
3995
+
o "closeafter": This MUST be one of the following values:
3996
+
3997
+
* "state": The server MUST end the HTTP response after pushing a
3998
+
state event. This can be used by clients in environments where
3999
+
buffering proxies prevent the pushed data from arriving
4000
+
immediately, or indeed at all, when operating in the usual
4001
+
mode.
4002
+
4003
+
* "no": The connection is persisted by the server as a standard
4004
+
event-source resource.
4005
+
4006
+
o "ping": A positive integer value representing a length of time in
4007
+
seconds, e.g., "300". If non-zero, the server MUST send an event
4008
+
called "ping" whenever this time elapses since the previous event
4009
+
was sent. This MUST NOT set a new event id. If the value is "0",
4010
+
the server MUST NOT send ping events.
4011
+
4012
+
The server MAY modify a requested ping interval to be subject to a
4013
+
minimum and/or maximum value. For interoperability, servers MUST
4014
+
NOT have a minimum allowed value higher than 30 or a maximum
4015
+
allowed value less than 300.
4016
+
4017
+
The data for the ping event MUST be a JSON object containing an
4018
+
"interval" property, the value (type "UnsignedInt") being the
4019
+
interval in seconds the server is using to send pings (this may be
4020
+
different to the requested value if the server clamped it to be
4021
+
within a min/max value).
4022
+
4023
+
Clients can monitor for the ping event to help determine when the
4024
+
closeafter mode may be required.
4025
+
4026
+
A client MAY hold open multiple connections to the event-source
4027
+
resource, although it SHOULD try to use a single connection for
4028
+
efficiency.
4029
+
4030
+
4031
+
4032
+
4033
+
4034
+
Jenkins & Newman Standards Track [Page 72]
4035
+
4036
+
RFC 8620 JMAP July 2019
4037
+
4038
+
4039
+
8. Security Considerations
4040
+
4041
+
8.1. Transport Confidentiality
4042
+
4043
+
To ensure the confidentiality and integrity of data sent and received
4044
+
via JMAP, all requests MUST use TLS 1.2 [RFC5246] [RFC8446] or later,
4045
+
following the recommendations in [RFC7525]. Servers SHOULD support
4046
+
TLS 1.3 [RFC8446] or later.
4047
+
4048
+
Clients MUST validate TLS certificate chains to protect against
4049
+
man-in-the-middle attacks [RFC5280].
4050
+
4051
+
8.2. Authentication Scheme
4052
+
4053
+
A number of HTTP authentication schemes have been standardised (see
4054
+
<https://www.iana.org/assignments/http-authschemes/>). Servers
4055
+
should take care to assess the security characteristics of different
4056
+
schemes in relation to their needs when deciding what to implement.
4057
+
4058
+
Use of the Basic authentication scheme is NOT RECOMMENDED. Services
4059
+
that choose to use it are strongly recommended to require generation
4060
+
of a unique "app password" via some external mechanism for each
4061
+
client they wish to connect. This allows connections from different
4062
+
devices to be differentiated by the server and access to be
4063
+
individually revoked.
4064
+
4065
+
8.3. Service Autodiscovery
4066
+
4067
+
Unless secured by something like DNSSEC, autodiscovery of server
4068
+
details using SRV DNS records is vulnerable to a DNS poisoning
4069
+
attack, which can lead to the client talking to an attacker's server
4070
+
instead of the real JMAP server. The attacker may then intercept
4071
+
requests to execute man-in-the-middle attacks and, depending on the
4072
+
authentication scheme, steal credentials to generate its own
4073
+
requests.
4074
+
4075
+
Clients that do not support SRV lookups are likely to try just using
4076
+
the "/.well-known/jmap" path directly against the domain of the
4077
+
username over HTTPS. Servers SHOULD ensure this path resolves or
4078
+
redirects to the correct JMAP Session resource to allow this to work.
4079
+
If this is not feasible, servers MUST ensure this path cannot be
4080
+
controlled by an attacker, as again it may be used to steal
4081
+
credentials.
4082
+
4083
+
4084
+
4085
+
4086
+
4087
+
4088
+
4089
+
4090
+
Jenkins & Newman Standards Track [Page 73]
4091
+
4092
+
RFC 8620 JMAP July 2019
4093
+
4094
+
4095
+
8.4. JSON Parsing
4096
+
4097
+
The Security Considerations of [RFC8259] apply to the use of JSON as
4098
+
the data interchange format.
4099
+
4100
+
As for any serialization format, parsers need to thoroughly check the
4101
+
syntax of the supplied data. JSON uses opening and closing tags for
4102
+
several types and structures, and it is possible that the end of the
4103
+
supplied data will be reached when scanning for a matching closing
4104
+
tag; this is an error condition, and implementations need to stop
4105
+
scanning at the end of the supplied data.
4106
+
4107
+
JSON also uses a string encoding with some escape sequences to encode
4108
+
special characters within a string. Care is needed when processing
4109
+
these escape sequences to ensure that they are fully formed before
4110
+
the special processing is triggered, with special care taken when the
4111
+
escape sequences appear adjacent to other (non-escaped) special
4112
+
characters or adjacent to the end of data (as in the previous
4113
+
paragraph).
4114
+
4115
+
If parsing JSON into a non-textual structured data format,
4116
+
implementations may need to allocate storage to hold JSON string
4117
+
elements. Since JSON does not use explicit string lengths, the risk
4118
+
of denial of service due to resource exhaustion is small, but
4119
+
implementations may still wish to place limits on the size of
4120
+
allocations they are willing to make in any given context, to avoid
4121
+
untrusted data causing excessive memory allocation.
4122
+
4123
+
8.5. Denial of Service
4124
+
4125
+
A small request may result in a very large response and require
4126
+
considerable work on the server if resource limits are not enforced.
4127
+
JMAP provides mechanisms for advertising and enforcing a wide variety
4128
+
of limits for mitigating this threat, including limits on the number
4129
+
of objects fetched in a single method call, number of methods in a
4130
+
single request, number of concurrent requests, etc.
4131
+
4132
+
JMAP servers MUST implement sensible limits to mitigate against
4133
+
resource exhaustion attacks.
4134
+
4135
+
8.6. Connection to Unknown Push Server
4136
+
4137
+
When a push subscription is registered, the application server will
4138
+
make POST requests to the given URL. There are a number of security
4139
+
considerations that MUST be considered when implementing this.
4140
+
4141
+
4142
+
4143
+
4144
+
4145
+
4146
+
Jenkins & Newman Standards Track [Page 74]
4147
+
4148
+
RFC 8620 JMAP July 2019
4149
+
4150
+
4151
+
The server MUST ensure the URL is externally resolvable to avoid
4152
+
server-side request forgery, where the server makes a request to a
4153
+
resource on its internal network.
4154
+
4155
+
A malicious client may use the push subscription to attempt to flood
4156
+
a third party server with requests, creating a denial-of-service
4157
+
attack and masking the attacker's true identity. There is no
4158
+
guarantee that the URL given to the JMAP server is actually a valid
4159
+
push server. Upon creation of a push subscription, the JMAP server
4160
+
sends a PushVerification object to the URL and MUST NOT send any
4161
+
further requests until the client verifies it has received the
4162
+
initial push. The verification code MUST contain sufficient entropy
4163
+
to prevent the client from being able to verify the subscription via
4164
+
brute force.
4165
+
4166
+
The verification code does not guarantee the URL is a valid push
4167
+
server, only that the client is able to access the data submitted to
4168
+
it. While the verification step significantly reduces the set of
4169
+
potential targets, there is still a risk that the server is unrelated
4170
+
to the client and being targeted for a denial-of-service attack.
4171
+
4172
+
The server MUST limit the number of push subscriptions any one user
4173
+
may have to ensure the user cannot cause the server to send a large
4174
+
number of push notifications at once, which could again be used as
4175
+
part of a denial-of-service attack. The rate of creation MUST also
4176
+
be limited to minimise the ability to abuse the verification request
4177
+
as an attack vector.
4178
+
4179
+
8.7. Push Encryption
4180
+
4181
+
When data changes, a small object is pushed with the new state
4182
+
strings for the types that have changed. While the data here is
4183
+
minimal, a passive man-in-the-middle attacker may be able to gain
4184
+
useful information. To ensure confidentiality and integrity, if the
4185
+
push is sent via a third party outside of the control of the client
4186
+
and JMAP server, the client MUST specify encryption keys when
4187
+
establishing the PushSubscription and ignore any push notification
4188
+
received that is not encrypted with those keys.
4189
+
4190
+
The privacy and security considerations of [RFC8030] and [RFC8291]
4191
+
also apply to the use of the PushSubscription mechanism.
4192
+
4193
+
As there is no crypto algorithm agility in Web Push Encryption
4194
+
[RFC8291], a new specification will be needed to provide this if new
4195
+
algorithms are required in the future.
4196
+
4197
+
4198
+
4199
+
4200
+
4201
+
4202
+
Jenkins & Newman Standards Track [Page 75]
4203
+
4204
+
RFC 8620 JMAP July 2019
4205
+
4206
+
4207
+
8.8. Traffic Analysis
4208
+
4209
+
While the data is encrypted, a passive observer with the ability to
4210
+
monitor network traffic may be able to glean information from the
4211
+
timing of API requests and push notifications. For example, suppose
4212
+
an email or calendar invitation is sent from User A (hosted on Server
4213
+
X) to User B (hosted on Server Y). If Server X hosts data for many
4214
+
users, a passive observer can see that the two servers connected but
4215
+
does not know who the data was for. However, if a push notification
4216
+
is immediately sent to User B and the attacker can observe this as
4217
+
well, they may reasonably conclude that someone on Server X is
4218
+
connecting to User B.
4219
+
4220
+
9. IANA Considerations
4221
+
4222
+
9.1. Assignment of jmap Service Name
4223
+
4224
+
IANA has assigned the 'jmap' service name in the "Service Name and
4225
+
Transport Protocol Port Number Registry" [RFC6335].
4226
+
4227
+
Service Name: jmap
4228
+
4229
+
Transport Protocol(s): tcp
4230
+
4231
+
Assignee: IESG
4232
+
4233
+
Contact: IETF Chair
4234
+
4235
+
Description: JSON Meta Application Protocol
4236
+
4237
+
Reference: RFC 8620
4238
+
4239
+
Assignment Notes: This service name was previously assigned under the
4240
+
name "JSON Mail Access Protocol". This has been de-assigned and
4241
+
re-assigned with the approval of the previous assignee.
4242
+
4243
+
9.2. Registration of Well-Known URI Suffix for JMAP
4244
+
4245
+
IANA has registered the following suffix in the "Well-Known URIs"
4246
+
registry for JMAP, as described in [RFC8615]:
4247
+
4248
+
URI Suffix: jmap
4249
+
4250
+
Change Controller: IETF
4251
+
4252
+
Specification Document: RFC 8620, Section 2.2.
4253
+
4254
+
4255
+
4256
+
4257
+
4258
+
Jenkins & Newman Standards Track [Page 76]
4259
+
4260
+
RFC 8620 JMAP July 2019
4261
+
4262
+
4263
+
9.3. Registration of the jmap URN Sub-namespace
4264
+
4265
+
IANA has registered the following URN sub-namespace in the "IETF URN
4266
+
Sub-namespace for Registered Protocol Parameter Identifiers" registry
4267
+
within the "Uniform Resource Name (URN) Namespace for IETF Use"
4268
+
registry as described in [RFC3553].
4269
+
4270
+
Registered Parameter Identifier: jmap
4271
+
4272
+
Reference: RFC 8620, Section 9.4
4273
+
4274
+
IANA Registry Reference: http://www.iana.org/assignments/jmap
4275
+
4276
+
9.4. Creation of "JMAP Capabilities" Registry
4277
+
4278
+
IANA has created the "JMAP Capabilities" registry as described in
4279
+
Section 2. JMAP capabilities are advertised in the "capabilities"
4280
+
property of the JMAP Session resource. They are used to extend the
4281
+
functionality of a JMAP server. A capability is referenced by a URI.
4282
+
The JMAP capability URI can be a URN starting with
4283
+
"urn:ietf:params:jmap:" plus a unique suffix that is the index value
4284
+
in the jmap URN sub-namespace. Registration of a JMAP capability
4285
+
with another form of URI has no impact on the jmap URN sub-namespace.
4286
+
4287
+
This registry follows the expert review process unless the "intended
4288
+
use" field is "common" or "placeholder", in which case registration
4289
+
follows the specification required process.
4290
+
4291
+
A JMAP capability registration can have an intended use of "common",
4292
+
"placeholder", "limited", or "obsolete". IANA will list common-use
4293
+
registrations prominently and separately from those with other
4294
+
intended use values.
4295
+
4296
+
The JMAP capability registration procedure is not a formal standards
4297
+
process but rather an administrative procedure intended to allow
4298
+
community comment and sanity checking without excessive time delay.
4299
+
4300
+
A "placeholder" registration reserves part of the jmap URN namespace
4301
+
for another purpose but is typically not included in the
4302
+
"capabilities" property of the JMAP Session resource.
4303
+
4304
+
9.4.1. Preliminary Community Review
4305
+
4306
+
Notice of a potential JMAP common-use registration SHOULD be sent to
4307
+
the JMAP mailing list <jmap@ietf.org> for review. This mailing list
4308
+
is appropriate to solicit community feedback on a proposed JMAP
4309
+
4310
+
4311
+
4312
+
4313
+
4314
+
Jenkins & Newman Standards Track [Page 77]
4315
+
4316
+
RFC 8620 JMAP July 2019
4317
+
4318
+
4319
+
capability. Registrations that are not intended for common use MAY
4320
+
be sent to the list for review as well; doing so is entirely
4321
+
OPTIONAL, but is encouraged.
4322
+
4323
+
The intent of the public posting to this list is to solicit comments
4324
+
and feedback on the choice of the capability name, the unambiguity of
4325
+
the specification document, and a review of any interoperability or
4326
+
security considerations. The submitter may submit a revised
4327
+
registration proposal or abandon the registration completely at any
4328
+
time.
4329
+
4330
+
9.4.2. Submit Request to IANA
4331
+
4332
+
Registration requests can be sent to <iana@iana.org>.
4333
+
4334
+
9.4.3. Designated Expert Review
4335
+
4336
+
For a limited-use registration, the primary concern of the designated
4337
+
expert (DE) is preventing name collisions and encouraging the
4338
+
submitter to document security and privacy considerations; a
4339
+
published specification is not required. For a common-use
4340
+
registration, the DE is expected to confirm that suitable
4341
+
documentation, as described in Section 4.6 of [RFC8126], is
4342
+
available. The DE should also verify that the capability does not
4343
+
conflict with work that is active or already published within the
4344
+
IETF.
4345
+
4346
+
Before a period of 30 days has passed, the DE will either approve or
4347
+
deny the registration request and publish a notice of the decision to
4348
+
the JMAP WG mailing list or its successor, as well as inform IANA. A
4349
+
denial notice must be justified by an explanation, and, in the cases
4350
+
where it is possible, concrete suggestions on how the request can be
4351
+
modified so as to become acceptable should be provided.
4352
+
4353
+
If the DE does not respond within 30 days, the registrant may request
4354
+
the IESG take action to process the request in a timely manner.
4355
+
4356
+
9.4.4. Change Procedures
4357
+
4358
+
Once a JMAP capability has been published by the IANA, the change
4359
+
controller may request a change to its definition. The same
4360
+
procedure that would be appropriate for the original registration
4361
+
request is used to process a change request.
4362
+
4363
+
JMAP capability registrations may not be deleted; capabilities that
4364
+
are no longer believed appropriate for use can be declared obsolete
4365
+
by a change to their "intended use" field; such capabilities will be
4366
+
clearly marked in the lists published by the IANA.
4367
+
4368
+
4369
+
4370
+
Jenkins & Newman Standards Track [Page 78]
4371
+
4372
+
RFC 8620 JMAP July 2019
4373
+
4374
+
4375
+
Significant changes to a capability's definition should be requested
4376
+
only when there are serious omissions or errors in the published
4377
+
specification. When review is required, a change request may be
4378
+
denied if it renders entities that were valid under the previous
4379
+
definition invalid under the new definition.
4380
+
4381
+
The owner of a JMAP capability may pass responsibility to another
4382
+
person or agency by informing the IANA; this can be done without
4383
+
discussion or review.
4384
+
4385
+
The IESG may reassign responsibility for a JMAP capability. The most
4386
+
common case of this will be to enable changes to be made to
4387
+
capabilities where the author of the registration has died, moved out
4388
+
of contact, or is otherwise unable to make changes that are important
4389
+
to the community.
4390
+
4391
+
9.4.5. JMAP Capabilities Registry Template
4392
+
4393
+
Capability name: (see capability property in Section 2)
4394
+
4395
+
Specification document:
4396
+
4397
+
Intended use: (one of common, limited, placeholder, or obsolete)
4398
+
4399
+
Change controller: ("IETF" for Standards Track / BCP RFCs)
4400
+
4401
+
Security and privacy considerations:
4402
+
4403
+
9.4.6. Initial Registration for JMAP Core
4404
+
4405
+
Capability Name: "urn:ietf:params:jmap:core"
4406
+
4407
+
Specification document: RFC 8620, Section 2
4408
+
4409
+
Intended use: common
4410
+
4411
+
Change Controller: IETF
4412
+
4413
+
Security and privacy considerations: RFC 8620, Section 8.
4414
+
4415
+
4416
+
4417
+
4418
+
4419
+
4420
+
4421
+
4422
+
4423
+
4424
+
4425
+
4426
+
Jenkins & Newman Standards Track [Page 79]
4427
+
4428
+
RFC 8620 JMAP July 2019
4429
+
4430
+
4431
+
9.4.7. Registration for JMAP Error Placeholder in JMAP Capabilities
4432
+
Registry
4433
+
4434
+
Capability Name: "urn:ietf:params:jmap:error:"
4435
+
4436
+
Specification document: RFC 8620, Section 9.5
4437
+
4438
+
Intended use: placeholder
4439
+
4440
+
Change Controller: IETF
4441
+
4442
+
Security and privacy considerations: RFC 8620, Section 8.
4443
+
4444
+
9.5. Creation of "JMAP Error Codes" Registry
4445
+
4446
+
IANA has created the "JMAP Error Codes" registry. JMAP error codes
4447
+
appear in the "type" member of a JSON problem details object (as
4448
+
described in Section 3.6.1), the "type" member in a JMAP error object
4449
+
(as described in Section 3.6.2), or the "type" member of a JMAP
4450
+
method-specific error object (such as SetError in Section 5.3). When
4451
+
used in a problem details object, the prefix
4452
+
"urn:ietf:params:jmap:error:" is always included; when used in JMAP
4453
+
objects, the prefix is always omitted.
4454
+
4455
+
This registry follows the expert review process. Preliminary
4456
+
community review for this registry follows the same procedures as the
4457
+
"JMAP Capabilities" registry, but it is optional. The change
4458
+
procedures for this registry are the same as the change procedures
4459
+
for the "JMAP Capabilities" registry.
4460
+
4461
+
9.5.1. Expert Review
4462
+
4463
+
The designated expert should review the following aspects of the
4464
+
registration:
4465
+
4466
+
1. Verify the error code does not conflict with existing names.
4467
+
4468
+
2. Verify the error code follows the syntax limitations (does not
4469
+
require URI encoding).
4470
+
4471
+
3. Encourage the submitter to follow the naming convention of
4472
+
previously registered errors.
4473
+
4474
+
4. Encourage the submitter to describe client behaviours that are
4475
+
recommended in response to the error code. These may distinguish
4476
+
the error code from other error codes.
4477
+
4478
+
4479
+
4480
+
4481
+
4482
+
Jenkins & Newman Standards Track [Page 80]
4483
+
4484
+
RFC 8620 JMAP July 2019
4485
+
4486
+
4487
+
5. Encourage the submitter to describe when the server should issue
4488
+
the error as opposed to some other error code.
4489
+
4490
+
6. Encourage the submitter to note any security considerations
4491
+
associated with the error, if any (e.g., an error code that might
4492
+
disclose existence of data the authenticated user does not have
4493
+
permission to know about).
4494
+
4495
+
Steps 3-6 are meant to promote a higher-quality registry. However,
4496
+
the expert is encouraged to approve any registration that would not
4497
+
actively harm JMAP interoperability to make this a relatively
4498
+
lightweight process.
4499
+
4500
+
9.5.2. JMAP Error Codes Registry Template
4501
+
4502
+
JMAP Error Code:
4503
+
4504
+
Intended use: (one of "common", "limited", "obsolete")
4505
+
4506
+
Change Controller: ("IETF" for Standards Track / BCP RFCs)
4507
+
4508
+
Reference: (Optional. Only required if defined in an RFC.)
4509
+
4510
+
Description:
4511
+
4512
+
9.5.3. Initial Contents for the JMAP Error Codes Registry
4513
+
4514
+
o JMAP Error Code: accountNotFound
4515
+
Intended Use: Common
4516
+
Change Controller: IETF
4517
+
Reference: RFC 8620, Section 3.6.2
4518
+
Description: The accountId does not correspond to a valid account.
4519
+
4520
+
o JMAP Error Code: accountNotSupportedByMethod
4521
+
Intended Use: Common
4522
+
Change Controller: IETF
4523
+
Reference: RFC 8620, Section 3.6.2
4524
+
Description: The accountId given corresponds to a valid account,
4525
+
but the account does not support this method or data type.
4526
+
4527
+
o JMAP Error Code: accountReadOnly
4528
+
Intended Use: Common
4529
+
Change Controller: IETF
4530
+
Reference: RFC 8620, Section 3.6.2
4531
+
Description: This method modifies state, but the account is read-
4532
+
only (as returned on the corresponding Account object in the JMAP
4533
+
Session resource).
4534
+
4535
+
4536
+
4537
+
4538
+
Jenkins & Newman Standards Track [Page 81]
4539
+
4540
+
RFC 8620 JMAP July 2019
4541
+
4542
+
4543
+
o JMAP Error Code: anchorNotFound
4544
+
Intended Use: Common
4545
+
Change Controller: IETF
4546
+
Reference: RFC 8620, Section 5.5
4547
+
Description: An anchor argument was supplied, but it cannot be
4548
+
found in the results of the query.
4549
+
4550
+
o JMAP Error Code: alreadyExists
4551
+
Intended Use: Common
4552
+
Change Controller: IETF
4553
+
Reference: RFC 8620, Section 5.4
4554
+
Description: The server forbids duplicates, and the record already
4555
+
exists in the target account. An existingId property of type Id
4556
+
MUST be included on the SetError object with the id of the
4557
+
existing record.
4558
+
4559
+
o JMAP Error Code: cannotCalculateChanges
4560
+
Intended Use: Common
4561
+
Change Controller: IETF
4562
+
Reference: RFC 8620, Sections 5.2 and 5.6
4563
+
Description: The server cannot calculate the changes from the
4564
+
state string given by the client.
4565
+
4566
+
o JMAP Error Code: forbidden
4567
+
Intended Use: Common
4568
+
Change Controller: IETF
4569
+
Reference: RFC 8620, Sections 3.6.2, 5.3, and 7.2.1
4570
+
Description: The action would violate an ACL or other permissions
4571
+
policy.
4572
+
4573
+
o JMAP Error Code: fromAccountNotFound
4574
+
Intended Use: Common
4575
+
Change Controller: IETF
4576
+
Reference: RFC 8620, Sections 5.4 and 6.3
4577
+
Description: The fromAccountId does not correspond to a valid
4578
+
account.
4579
+
4580
+
o JMAP Error Code: fromAccountNotSupportedByMethod
4581
+
Intended Use: Common
4582
+
Change Controller: IETF
4583
+
Reference: RFC 8620, Section 5.4
4584
+
Description: The fromAccountId given corresponds to a valid
4585
+
account, but the account does not support this data type.
4586
+
4587
+
4588
+
4589
+
4590
+
4591
+
4592
+
4593
+
4594
+
Jenkins & Newman Standards Track [Page 82]
4595
+
4596
+
RFC 8620 JMAP July 2019
4597
+
4598
+
4599
+
o JMAP Error Code: invalidArguments
4600
+
Intended Use: Common
4601
+
Change Controller: IETF
4602
+
Reference: RFC 8620, Section 3.6.2
4603
+
Description: One of the arguments is of the wrong type or
4604
+
otherwise invalid, or a required argument is missing.
4605
+
4606
+
o JMAP Error Code: invalidPatch
4607
+
Intended Use: Common
4608
+
Change Controller: IETF
4609
+
Reference: RFC 8620, Section 5.3
4610
+
Description: The PatchObject given to update the record was not a
4611
+
valid patch.
4612
+
4613
+
o JMAP Error Code: invalidProperties
4614
+
Intended Use: Common
4615
+
Change Controller: IETF
4616
+
Reference: RFC 8620, Section 5.3
4617
+
Description: The record given is invalid.
4618
+
4619
+
o JMAP Error Code: notFound
4620
+
Intended Use: Common
4621
+
Change Controller: IETF
4622
+
Reference: RFC 8620, Section 5.3
4623
+
Description: The id given cannot be found.
4624
+
4625
+
o JMAP Error Code: notJSON
4626
+
Intended Use: Common
4627
+
Change Controller: IETF
4628
+
Reference: RFC 8620, Section 3.6.1
4629
+
Description: The content type of the request was not application/
4630
+
json, or the request did not parse as I-JSON.
4631
+
4632
+
o JMAP Error Code: notRequest
4633
+
Intended Use: Common
4634
+
Change Controller: IETF
4635
+
Reference: RFC 8620, Section 3.6.1
4636
+
Description: The request parsed as JSON but did not match the type
4637
+
signature of the Request object.
4638
+
4639
+
o JMAP Error Code: overQuota
4640
+
Intended Use: Common
4641
+
Change Controller: IETF
4642
+
Reference: RFC 8620, Section 5.3
4643
+
Description: The create would exceed a server-defined limit on the
4644
+
number or total size of objects of this type.
4645
+
4646
+
4647
+
4648
+
4649
+
4650
+
Jenkins & Newman Standards Track [Page 83]
4651
+
4652
+
RFC 8620 JMAP July 2019
4653
+
4654
+
4655
+
o JMAP Error Code: rateLimit
4656
+
Intended Use: Common
4657
+
Change Controller: IETF
4658
+
Reference: RFC 8620, Section 5.3
4659
+
Description: Too many objects of this type have been created
4660
+
recently, and a server-defined rate limit has been reached. It
4661
+
may work if tried again later.
4662
+
4663
+
o JMAP Error Code: requestTooLarge
4664
+
Intended Use: Common
4665
+
Change Controller: IETF
4666
+
Reference: RFC 8620, Sections 5.1 and 5.3
4667
+
Description: The total number of actions exceeds the maximum
4668
+
number the server is willing to process in a single method call.
4669
+
4670
+
o JMAP Error Code: invalidResultReference
4671
+
Intended Use: Common
4672
+
Change Controller: IETF
4673
+
Reference: RFC 8620, Section 3.6.2
4674
+
Description: The method used a result reference for one of its
4675
+
arguments, but this failed to resolve.
4676
+
4677
+
o JMAP Error Code: serverFail
4678
+
Intended Use: Common
4679
+
Change Controller: IETF
4680
+
Reference: RFC 8620, Section 3.6.2
4681
+
Description: An unexpected or unknown error occurred during the
4682
+
processing of the call. The method call made no changes to the
4683
+
server's state.
4684
+
4685
+
o JMAP Error Code: serverPartialFail
4686
+
Intended Use: Limited
4687
+
Change Controller: IETF
4688
+
Reference: RFC 8620, Section 3.6.2
4689
+
Description: Some, but not all, expected changes described by the
4690
+
method occurred. The client MUST resynchronise impacted data to
4691
+
determine the server state. Use of this error is strongly
4692
+
discouraged.
4693
+
4694
+
o JMAP Error Code: serverUnavailable
4695
+
Intended Use: Common
4696
+
Change Controller: IETF
4697
+
Reference: RFC 8620, Section 3.6.2
4698
+
Description: Some internal server resource was temporarily
4699
+
unavailable. Attempting the same operation later (perhaps after a
4700
+
backoff with a random factor) may succeed.
4701
+
4702
+
4703
+
4704
+
4705
+
4706
+
Jenkins & Newman Standards Track [Page 84]
4707
+
4708
+
RFC 8620 JMAP July 2019
4709
+
4710
+
4711
+
o JMAP Error Code: singleton
4712
+
Intended Use: Common
4713
+
Change Controller: IETF
4714
+
Reference: RFC 8620, Section 5.3
4715
+
Description: This is a singleton type, so you cannot create
4716
+
another one or destroy the existing one.
4717
+
4718
+
o JMAP Error Code: stateMismatch
4719
+
Intended Use: Common
4720
+
Change Controller: IETF
4721
+
Reference: RFC 8620, Section 5.3
4722
+
Description: An ifInState argument was supplied, and it does not
4723
+
match the current state.
4724
+
4725
+
o JMAP Error Code: tooLarge
4726
+
Intended Use: Common
4727
+
Change Controller: IETF
4728
+
Reference: RFC 8620, Section 5.3
4729
+
Description: The action would result in an object that exceeds a
4730
+
server-defined limit for the maximum size of a single object of
4731
+
this type.
4732
+
4733
+
o JMAP Error Code: tooManyChanges
4734
+
Intended Use: Common
4735
+
Change Controller: IETF
4736
+
Reference: RFC 8620, Section 5.6
4737
+
Description: There are more changes than the client's maxChanges
4738
+
argument.
4739
+
4740
+
o JMAP Error Code: unknownCapability
4741
+
Intended Use: Common
4742
+
Change Controller: IETF
4743
+
Reference: RFC 8620, Section 3.6.1
4744
+
Description: The client included a capability in the "using"
4745
+
property of the request that the server does not support.
4746
+
4747
+
o JMAP Error Code: unknownMethod
4748
+
Intended Use: Common
4749
+
Change Controller: IETF
4750
+
Reference: RFC 8620, Section 3.6.2
4751
+
Description: The server does not recognise this method name.
4752
+
4753
+
o JMAP Error Code: unsupportedFilter
4754
+
Intended Use: Common
4755
+
Change Controller: IETF
4756
+
Reference: RFC 8620, Section 5.5
4757
+
Description: The filter is syntactically valid, but the server
4758
+
cannot process it.
4759
+
4760
+
4761
+
4762
+
Jenkins & Newman Standards Track [Page 85]
4763
+
4764
+
RFC 8620 JMAP July 2019
4765
+
4766
+
4767
+
o JMAP Error Code: unsupportedSort
4768
+
Intended Use: Common
4769
+
Change Controller: IETF
4770
+
Reference: RFC 8620, Section 5.5
4771
+
Description: The sort is syntactically valid but includes a
4772
+
property the server does not support sorting on or a collation
4773
+
method it does not recognise.
4774
+
4775
+
o JMAP Error Code: willDestroy
4776
+
Intended Use: Common
4777
+
Change Controller: IETF
4778
+
Reference: RFC 8620, Section 5.3
4779
+
Description: The client requested an object be both updated and
4780
+
destroyed in the same /set request, and the server has decided to
4781
+
therefore ignore the update.
4782
+
4783
+
10. References
4784
+
4785
+
10.1. Normative References
4786
+
4787
+
[EventSource]
4788
+
Hickson, I., "Server-Sent Events", World Wide Web
4789
+
Consortium Recommendation REC-eventsource-20150203,
4790
+
February 2015, <https://www.w3.org/TR/eventsource/>.
4791
+
4792
+
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
4793
+
Requirement Levels", BCP 14, RFC 2119,
4794
+
DOI 10.17487/RFC2119, March 1997,
4795
+
<https://www.rfc-editor.org/info/rfc2119>.
4796
+
4797
+
[RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for
4798
+
specifying the location of services (DNS SRV)", RFC 2782,
4799
+
DOI 10.17487/RFC2782, February 2000,
4800
+
<https://www.rfc-editor.org/info/rfc2782>.
4801
+
4802
+
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
4803
+
DOI 10.17487/RFC2818, May 2000,
4804
+
<https://www.rfc-editor.org/info/rfc2818>.
4805
+
4806
+
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
4807
+
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
4808
+
<https://www.rfc-editor.org/info/rfc3339>.
4809
+
4810
+
[RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An
4811
+
IETF URN Sub-namespace for Registered Protocol
4812
+
Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June
4813
+
2003, <https://www.rfc-editor.org/info/rfc3553>.
4814
+
4815
+
4816
+
4817
+
4818
+
Jenkins & Newman Standards Track [Page 86]
4819
+
4820
+
RFC 8620 JMAP July 2019
4821
+
4822
+
4823
+
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
4824
+
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
4825
+
2003, <https://www.rfc-editor.org/info/rfc3629>.
4826
+
4827
+
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
4828
+
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
4829
+
<https://www.rfc-editor.org/info/rfc4648>.
4830
+
4831
+
[RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
4832
+
Application Protocol Collation Registry", RFC 4790,
4833
+
DOI 10.17487/RFC4790, March 2007,
4834
+
<https://www.rfc-editor.org/info/rfc4790>.
4835
+
4836
+
[RFC5051] Crispin, M., "i;unicode-casemap - Simple Unicode Collation
4837
+
Algorithm", RFC 5051, DOI 10.17487/RFC5051, October 2007,
4838
+
<https://www.rfc-editor.org/info/rfc5051>.
4839
+
4840
+
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
4841
+
(TLS) Protocol Version 1.2", RFC 5246,
4842
+
DOI 10.17487/RFC5246, August 2008,
4843
+
<https://www.rfc-editor.org/info/rfc5246>.
4844
+
4845
+
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
4846
+
Housley, R., and W. Polk, "Internet X.509 Public Key
4847
+
Infrastructure Certificate and Certificate Revocation List
4848
+
(CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
4849
+
<https://www.rfc-editor.org/info/rfc5280>.
4850
+
4851
+
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
4852
+
DOI 10.17487/RFC5322, October 2008,
4853
+
<https://www.rfc-editor.org/info/rfc5322>.
4854
+
4855
+
[RFC6186] Daboo, C., "Use of SRV Records for Locating Email
4856
+
Submission/Access Services", RFC 6186,
4857
+
DOI 10.17487/RFC6186, March 2011,
4858
+
<https://www.rfc-editor.org/info/rfc6186>.
4859
+
4860
+
[RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S.
4861
+
Cheshire, "Internet Assigned Numbers Authority (IANA)
4862
+
Procedures for the Management of the Service Name and
4863
+
Transport Protocol Port Number Registry", BCP 165,
4864
+
RFC 6335, DOI 10.17487/RFC6335, August 2011,
4865
+
<https://www.rfc-editor.org/info/rfc6335>.
4866
+
4867
+
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
4868
+
and D. Orchard, "URI Template", RFC 6570,
4869
+
DOI 10.17487/RFC6570, March 2012,
4870
+
<https://www.rfc-editor.org/info/rfc6570>.
4871
+
4872
+
4873
+
4874
+
Jenkins & Newman Standards Track [Page 87]
4875
+
4876
+
RFC 8620 JMAP July 2019
4877
+
4878
+
4879
+
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
4880
+
RFC 6749, DOI 10.17487/RFC6749, October 2012,
4881
+
<https://www.rfc-editor.org/info/rfc6749>.
4882
+
4883
+
[RFC6764] Daboo, C., "Locating Services for Calendaring Extensions
4884
+
to WebDAV (CalDAV) and vCard Extensions to WebDAV
4885
+
(CardDAV)", RFC 6764, DOI 10.17487/RFC6764, February 2013,
4886
+
<https://www.rfc-editor.org/info/rfc6764>.
4887
+
4888
+
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
4889
+
Specifications and Registration Procedures", BCP 13,
4890
+
RFC 6838, DOI 10.17487/RFC6838, January 2013,
4891
+
<https://www.rfc-editor.org/info/rfc6838>.
4892
+
4893
+
[RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed.,
4894
+
"JavaScript Object Notation (JSON) Pointer", RFC 6901,
4895
+
DOI 10.17487/RFC6901, April 2013,
4896
+
<https://www.rfc-editor.org/info/rfc6901>.
4897
+
4898
+
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
4899
+
Protocol (HTTP/1.1): Message Syntax and Routing",
4900
+
RFC 7230, DOI 10.17487/RFC7230, June 2014,
4901
+
<https://www.rfc-editor.org/info/rfc7230>.
4902
+
4903
+
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
4904
+
Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
4905
+
DOI 10.17487/RFC7231, June 2014,
4906
+
<https://www.rfc-editor.org/info/rfc7231>.
4907
+
4908
+
[RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
4909
+
DOI 10.17487/RFC7493, March 2015,
4910
+
<https://www.rfc-editor.org/info/rfc7493>.
4911
+
4912
+
[RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre,
4913
+
"Recommendations for Secure Use of Transport Layer
4914
+
Security (TLS) and Datagram Transport Layer Security
4915
+
(DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May
4916
+
2015, <https://www.rfc-editor.org/info/rfc7525>.
4917
+
4918
+
[RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme",
4919
+
RFC 7617, DOI 10.17487/RFC7617, September 2015,
4920
+
<https://www.rfc-editor.org/info/rfc7617>.
4921
+
4922
+
[RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP
4923
+
APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016,
4924
+
<https://www.rfc-editor.org/info/rfc7807>.
4925
+
4926
+
4927
+
4928
+
4929
+
4930
+
Jenkins & Newman Standards Track [Page 88]
4931
+
4932
+
RFC 8620 JMAP July 2019
4933
+
4934
+
4935
+
[RFC8030] Thomson, M., Damaggio, E., and B. Raymor, Ed., "Generic
4936
+
Event Delivery Using HTTP Push", RFC 8030,
4937
+
DOI 10.17487/RFC8030, December 2016,
4938
+
<https://www.rfc-editor.org/info/rfc8030>.
4939
+
4940
+
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
4941
+
Writing an IANA Considerations Section in RFCs", BCP 26,
4942
+
RFC 8126, DOI 10.17487/RFC8126, June 2017,
4943
+
<https://www.rfc-editor.org/info/rfc8126>.
4944
+
4945
+
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
4946
+
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
4947
+
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
4948
+
4949
+
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
4950
+
Interchange Format", STD 90, RFC 8259,
4951
+
DOI 10.17487/RFC8259, December 2017,
4952
+
<https://www.rfc-editor.org/info/rfc8259>.
4953
+
4954
+
[RFC8264] Saint-Andre, P. and M. Blanchet, "PRECIS Framework:
4955
+
Preparation, Enforcement, and Comparison of
4956
+
Internationalized Strings in Application Protocols",
4957
+
RFC 8264, DOI 10.17487/RFC8264, October 2017,
4958
+
<https://www.rfc-editor.org/info/rfc8264>.
4959
+
4960
+
[RFC8291] Thomson, M., "Message Encryption for Web Push", RFC 8291,
4961
+
DOI 10.17487/RFC8291, November 2017,
4962
+
<https://www.rfc-editor.org/info/rfc8291>.
4963
+
4964
+
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
4965
+
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
4966
+
<https://www.rfc-editor.org/info/rfc8446>.
4967
+
4968
+
[RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers
4969
+
(URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019,
4970
+
<https://www.rfc-editor.org/info/rfc8615>.
4971
+
4972
+
10.2. Informative References
4973
+
4974
+
[RFC8246] McManus, P., "HTTP Immutable Responses", RFC 8246,
4975
+
DOI 10.17487/RFC8246, September 2017,
4976
+
<https://www.rfc-editor.org/info/rfc8246>.
4977
+
4978
+
4979
+
4980
+
4981
+
4982
+
4983
+
4984
+
4985
+
4986
+
Jenkins & Newman Standards Track [Page 89]
4987
+
4988
+
RFC 8620 JMAP July 2019
4989
+
4990
+
4991
+
Authors' Addresses
4992
+
4993
+
Neil Jenkins
4994
+
Fastmail
4995
+
PO Box 234, Collins St. West
4996
+
Melbourne, VIC 8007
4997
+
Australia
4998
+
4999
+
Email: neilj@fastmailteam.com
5000
+
URI: https://www.fastmail.com
5001
+
5002
+
5003
+
Chris Newman
5004
+
Oracle
5005
+
440 E. Huntington Dr., Suite 400
5006
+
Arcadia, CA 91006
5007
+
United States of America
5008
+
5009
+
Email: chris.newman@oracle.com
5010
+
5011
+
5012
+
5013
+
5014
+
5015
+
5016
+
5017
+
5018
+
5019
+
5020
+
5021
+
5022
+
5023
+
5024
+
5025
+
5026
+
5027
+
5028
+
5029
+
5030
+
5031
+
5032
+
5033
+
5034
+
5035
+
5036
+
5037
+
5038
+
5039
+
5040
+
5041
+
5042
+
Jenkins & Newman Standards Track [Page 90]
5043
+