RFC 8620
The JSON Meta Application Protocol (JMAP)
5. Standard Methods and Naming Convention
JMAP provides a uniform interface for creating, retrieving, updating, and deleting objects of a particular type. For a "Foo" data type, records of that type would be fetched via a "Foo/get" call and modified via a "Foo/set" call. Delta updates may be fetched via a "Foo/changes" call. These methods all follow a standard format as described below. Some types may not have all these methods. Specifications defining types MUST specify which methods are available for the type.5.1. /get
Objects of type Foo are fetched via a call to "Foo/get". It takes the following arguments: o accountId: "Id" The id of the account to use. o ids: "Id[]|null" The ids of the Foo objects to return. If null, then *all* records of the data type are returned, if this is supported for that data type and the number of records does not exceed the "maxObjectsInGet" limit. o properties: "String[]|null" If supplied, only the properties listed in the array are returned for each Foo object. If null, all properties of the object are returned. The id property of the object is *always* returned, even if not explicitly requested. If an invalid property is requested, the call MUST be rejected with an "invalidArguments" error. The response has the following arguments: o accountId: "Id" The id of the account used for the call.
o state: "String"
A (preferably short) string representing the state on the server
for *all* the data of this type in the account (not just the
objects returned in this call). If the data changes, this string
MUST change. If the Foo data is unchanged, servers SHOULD return
the same state string on subsequent requests for this data type.
When a client receives a response with a different state string to
a previous call, it MUST either throw away all currently cached
objects for the type or call "Foo/changes" to get the exact
changes.
o list: "Foo[]"
An array of the Foo objects requested. This is the *empty array*
if no objects were found or if the "ids" argument passed in was
also an empty array. The results MAY be in a different order to
the "ids" in the request arguments. If an identical id is
included more than once in the request, the server MUST only
include it once in either the "list" or the "notFound" argument of
the response.
o notFound: "Id[]"
This array contains the ids passed to the method for records that
do not exist. The array is empty if all requested ids were found
or if the "ids" argument passed in was either null or an empty
array.
The following additional error may be returned instead of the "Foo/
get" response:
"requestTooLarge": The number of ids requested by the client exceeds
the maximum number the server is willing to process in a single
method call.
5.2. /changes
When the state of the set of Foo records in an account changes on the
server (whether due to creation, updates, or deletion), the "state"
property of the "Foo/get" response will change. The "Foo/changes"
method allows a client to efficiently update the state of its Foo
cache to match the new state on the server. It takes the following
arguments:
o accountId: "Id"
The id of the account to use.
o sinceState: "String"
The current state of the client. This is the string that was
returned as the "state" argument in the "Foo/get" response. The
server will return the changes that have occurred since this
state.
o maxChanges: "UnsignedInt|null"
The maximum number of ids to return in the response. The server
MAY choose to return fewer than this value but MUST NOT return
more. If not given by the client, the server may choose how many
to return. If supplied by the client, the value MUST be a
positive integer greater than 0. If a value outside of this range
is given, the server MUST reject the call with an
"invalidArguments" error.
The response has the following arguments:
o accountId: "Id"
The id of the account used for the call.
o oldState: "String"
This is the "sinceState" argument echoed back; it's the state from
which the server is returning changes.
o newState: "String"
This is the state the client will be in after applying the set of
changes to the old state.
o hasMoreChanges: "Boolean"
If true, the client may call "Foo/changes" again with the
"newState" returned to get further updates. If false, "newState"
is the current server state.
o created: "Id[]"
An array of ids for records that have been created since the old
state.
o updated: "Id[]"
An array of ids for records that have been updated since the old
state.
o destroyed: "Id[]"
An array of ids for records that have been destroyed since the old
state.
If a record has been created AND updated since the old state, the
server SHOULD just return the id in the "created" list but MAY return
it in the "updated" list as well.
If a record has been updated AND destroyed since the old state, the
server SHOULD just return the id in the "destroyed" list but MAY
return it in the "updated" list as well.
If a record has been created AND destroyed since the old state, the
server SHOULD remove the id from the response entirely. However, it
MAY include it in just the "destroyed" list or in both the
"destroyed" and "created" lists.
If a "maxChanges" is supplied, or set automatically by the server,
the server MUST ensure the number of ids returned across "created",
"updated", and "destroyed" does not exceed this limit. If there are
more changes than this between the client's state and the current
server state, the server SHOULD generate an update to take the client
to an intermediate state, from which the client can continue to call
"Foo/changes" until it is fully up to date. If it is unable to
calculate an intermediate state, it MUST return a
"cannotCalculateChanges" error response instead.
When generating intermediate states, the server may choose how to
divide up the changes. For many types, it will provide a better user
experience to return the more recent changes first, as this is more
likely to be what the user is most interested in. The client can
then continue to page in the older changes while the user is viewing
the newer data. For example, suppose a server went through the
following states:
A -> B -> C -> D -> E
And a client asks for changes from state "B". The server might first
get the ids of records created, updated, or destroyed between states
D and E, returning them with:
state: "B-D-E"
hasMoreChanges: true
The client will then ask for the change from state "B-D-E", and the
server can return the changes between states C and D, returning:
state: "B-C-E"
hasMoreChanges: true
Finally, the client will request the changes from "B-C-E", and the
server can return the changes between states B and C, returning:
state: "E"
hasMoreChanges: false
Should the state on the server be modified in the middle of all this
(to "F"), the server still does the same, but now when the update to
state "E" is returned, it would indicate that it still has more
changes for the client to fetch.
Where multiple changes to a record are split across different
intermediate states, the server MUST NOT return a record as created
after a response that deems it as updated or destroyed, and it MUST
NOT return a record as destroyed before a response that deems it as
created or updated. The server may have to coalesce multiple changes
to a record to satisfy this requirement.
The following additional errors may be returned instead of the "Foo/
changes" response:
"cannotCalculateChanges": The server cannot calculate the changes
from the state string given by the client. Usually, this is due to
the client's state being too old or the server being unable to
produce an update to an intermediate state when there are too many
updates. The client MUST invalidate its Foo cache.
Maintaining state to allow calculation of "Foo/changes" can be
expensive for the server, but always returning
"cannotCalculateChanges" severely increases network traffic and
resource usage for the client. To allow efficient sync, servers
SHOULD be able to calculate changes from any state string that was
given to a client within the last 30 days (but of course may support
calculating updates from states older than this).
5.3. /set
Modifying the state of Foo objects on the server is done via the "Foo/set" method. This encompasses creating, updating, and destroying Foo records. This allows the server to sort out ordering and dependencies that may exist if doing multiple operations at once (for example, to ensure there is always a minimum number of a certain record type). The "Foo/set" method takes the following arguments: o accountId: "Id" The id of the account to use. o ifInState: "String|null" This is a state string as returned by the "Foo/get" method (representing the state of all objects of this type in the account). If supplied, the string must match the current state; otherwise, the method will be aborted and a "stateMismatch" error returned. If null, any changes will be applied to the current state. o create: "Id[Foo]|null" A map of a *creation id* (a temporary id set by the client) to Foo objects, or null if no objects are to be created. The Foo object type definition may define default values for properties. Any such property may be omitted by the client. The client MUST omit any properties that may only be set by the server (for example, the "id" property on most object types). o update: "Id[PatchObject]|null" A map of an id to a Patch object to apply to the current Foo object with that id, or null if no objects are to be updated. A *PatchObject* is of type "String[*]" and represents an unordered set of patches. The keys are a path in JSON Pointer format [RFC6901], with an implicit leading "/" (i.e., prefix each key with "/" before applying the JSON Pointer evaluation algorithm). All paths MUST also conform to the following restrictions; if there is any violation, the update MUST be rejected with an "invalidPatch" error:
* The pointer MUST NOT reference inside an array (i.e., you MUST
NOT insert/delete from an array; the array MUST be replaced in
its entirety instead).
* All parts prior to the last (i.e., the value after the final
slash) MUST already exist on the object being patched.
* There MUST NOT be two patches in the PatchObject where the
pointer of one is the prefix of the pointer of the other, e.g.,
"alerts/1/offset" and "alerts".
The value associated with each pointer determines how to apply
that patch:
* If null, set to the default value if specified for this
property; otherwise, remove the property from the patched
object. If the key is not present in the parent, this a no-op.
* Anything else: The value to set for this property (this may be
a replacement or addition to the object being patched).
Any server-set properties MAY be included in the patch if their
value is identical to the current server value (before applying
the patches to the object). Otherwise, the update MUST be
rejected with an "invalidProperties" SetError.
This patch definition is designed such that an entire Foo object
is also a valid PatchObject. The client may choose to optimise
network usage by just sending the diff or may send the whole
object; the server processes it the same either way.
o destroy: "Id[]|null"
A list of ids for Foo objects to permanently delete, or null if no
objects are to be destroyed.
Each creation, modification, or destruction of an object is
considered an atomic unit. It is permissible for the server to
commit changes to some objects but not others; however, it MUST NOT
only commit part of an update to a single record (e.g., update a
"name" property but not a "count" property, if both are supplied in
the update object).
The final state MUST be valid after the "Foo/set" is finished;
however, the server may have to transition through invalid
intermediate states (not exposed to the client) while processing the
individual create/update/destroy requests. For example, suppose
there is a "name" property that must be unique. A single method call
could rename an object A => B and simultaneously rename another object B => A. If the final state is valid, this is allowed. Otherwise, each creation, modification, or destruction of an object should be processed sequentially and accepted/rejected based on the current server state. If a create, update, or destroy is rejected, the appropriate error MUST be added to the notCreated/notUpdated/notDestroyed property of the response, and the server MUST continue to the next create/update/ destroy. It does not terminate the method. If an id given cannot be found, the update or destroy MUST be rejected with a "notFound" set error. The server MAY skip an update (rejecting it with a "willDestroy" SetError) if that object is destroyed in the same /set request. Some records may hold references to other records (foreign keys). That reference may be set (via create or update) in the same request as the referenced record is created. To do this, the client refers to the new record using its creation id prefixed with a "#". The order of the method calls in the request by the client MUST be such that the record being referenced is created in the same or an earlier call. Thus, the server never has to look ahead. Instead, while processing a request, the server MUST keep a simple map for the duration of the request of creation id to record id for each newly created record, so it can substitute in the correct value if necessary in later method calls. In the case of records with references to the same type, the server MUST order the creates and updates within a single method call so that creates happen before their creation ids are referenced by another create/update/destroy in the same call. Creation ids are not scoped by type but are a single map for all types. A client SHOULD NOT reuse a creation id anywhere in the same API request. If a creation id is reused, the server MUST map the creation id to the most recently created item with that id. To allow easy proxying of API requests, an initial set of creation id to real id values may be passed with a request (see "The Request Object", Section 3.3) and the final state of the map passed out with the response (see "The Response Object", Section 3.4). The response has the following arguments: o accountId: "Id" The id of the account used for the call.
o oldState: "String|null"
The state string that would have been returned by "Foo/get" before
making the requested changes, or null if the server doesn't know
what the previous state string was.
o newState: "String"
The state string that will now be returned by "Foo/get".
o created: "Id[Foo]|null"
A map of the creation id to an object containing any properties of
the created Foo object that were not sent by the client. This
includes all server-set properties (such as the "id" in most
object types) and any properties that were omitted by the client
and thus set to a default by the server.
This argument is null if no Foo objects were successfully created.
o updated: "Id[Foo|null]|null"
The keys in this map are the ids of all Foos that were
successfully updated.
The value for each id is a Foo object containing any property that
changed in a way *not* explicitly requested by the PatchObject
sent to the server, or null if none. This lets the client know of
any changes to server-set or computed properties.
This argument is null if no Foo objects were successfully updated.
o destroyed: "Id[]|null"
A list of Foo ids for records that were successfully destroyed, or
null if none.
o notCreated: "Id[SetError]|null"
A map of the creation id to a SetError object for each record that
failed to be created, or null if all successful.
o notUpdated: "Id[SetError]|null"
A map of the Foo id to a SetError object for each record that
failed to be updated, or null if all successful.
o notDestroyed: "Id[SetError]|null"
A map of the Foo id to a SetError object for each record that
failed to be destroyed, or null if all successful.
A *SetError* object has the following properties:
o type: "String"
The type of error.
o description: "String|null"
A description of the error to help with debugging that includes an
explanation of what the problem was. This is a non-localised
string and is not intended to be shown directly to end users.
The following SetError types are defined and may be returned for set
operations on any record type where appropriate:
o "forbidden": (create; update; destroy). The create/update/destroy
would violate an ACL or other permissions policy.
o "overQuota": (create; update). The create would exceed a server-
defined limit on the number or total size of objects of this type.
o "tooLarge": (create; update). The create/update would result in
an object that exceeds a server-defined limit for the maximum size
of a single object of this type.
o "rateLimit": (create). Too many objects of this type have been
created recently, and a server-defined rate limit has been
reached. It may work if tried again later.
o "notFound": (update; destroy). The id given to update/destroy
cannot be found.
o "invalidPatch": (update). The PatchObject given to update the
record was not a valid patch (see the patch description).
o "willDestroy": (update). The client requested that an object be
both updated and destroyed in the same /set request, and the
server has decided to therefore ignore the update.
o "invalidProperties": (create; update). The record given is
invalid in some way. For example:
* It contains properties that are invalid according to the type
specification of this record type.
* It contains a property that may only be set by the server
(e.g., "id") and is different to the current value. Note, to
allow clients to pass whole objects back, it is not an error to
include a server-set property in an update as long as the value
is identical to the current value on the server.
* There is a reference to another record (foreign key), and the
given id does not correspond to a valid record.
The SetError object SHOULD also have a property called
"properties" of type "String[]" that lists *all* the properties
that were invalid.
Individual methods MAY specify more specific errors for certain
conditions that would otherwise result in an invalidProperties
error. If the condition of one of these is met, it MUST be
returned instead of the invalidProperties error.
o "singleton": (create; destroy). This is a singleton type, so you
cannot create another one or destroy the existing one.
Other possible SetError types MAY be given in specific method
descriptions. Other properties MAY also be present on the SetError
object, as described in the relevant methods.
The following additional errors may be returned instead of the "Foo/
set" response:
"requestTooLarge": The total number of objects to create, update, or
destroy exceeds the maximum number the server is willing to process
in a single method call.
"stateMismatch": An "ifInState" argument was supplied, and it does
not match the current state.
5.4. /copy
The only way to move Foo records *between* two different accounts is to copy them using the "Foo/copy" method; once the copy has succeeded, delete the original. The "onSuccessDestroyOriginal" argument allows you to try to do this in one method call; however, note that the two different actions are not atomic, so it is possible for the copy to succeed but the original not to be destroyed for some reason. The copy is conceptually in three phases: 1. Reading the current values from the "from" account. 2. Writing the new copies to the other account. 3. Destroying the originals in the "from" account, if requested. Data may change in between phases due to concurrent requests. The "Foo/copy" method takes the following arguments: o fromAccountId: "Id" The id of the account to copy records from. o ifFromInState: "String|null" This is a state string as returned by the "Foo/get" method. If supplied, the string must match the current state of the account referenced by the fromAccountId when reading the data to be copied; otherwise, the method will be aborted and a "stateMismatch" error returned. If null, the data will be read from the current state. o accountId: "Id" The id of the account to copy records to. This MUST be different to the "fromAccountId". o ifInState: "String|null" This is a state string as returned by the "Foo/get" method. If supplied, the string must match the current state of the account referenced by the accountId; otherwise, the method will be aborted and a "stateMismatch" error returned. If null, any changes will be applied to the current state.
o create: "Id[Foo]"
A map of the *creation id* to a Foo object. The Foo object MUST
contain an "id" property, which is the id (in the fromAccount) of
the record to be copied. When creating the copy, any other
properties included are used instead of the current value for that
property on the original.
o onSuccessDestroyOriginal: "Boolean" (default: false)
If true, an attempt will be made to destroy the original records
that were successfully copied: after emitting the "Foo/copy"
response, but before processing the next method, the server MUST
make a single call to "Foo/set" to destroy the original of each
successfully copied record; the output of this is added to the
responses as normal, to be returned to the client.
o destroyFromIfInState: "String|null"
This argument is passed on as the "ifInState" argument to the
implicit "Foo/set" call, if made at the end of this request to
destroy the originals that were successfully copied.
Each record copy is considered an atomic unit that may succeed or
fail individually.
The response has the following arguments:
o fromAccountId: "Id"
The id of the account records were copied from.
o accountId: "Id"
The id of the account records were copied to.
o oldState: "String|null"
The state string that would have been returned by "Foo/get" on the
account records that were copied to before making the requested
changes, or null if the server doesn't know what the previous
state string was.
o newState: "String"
The state string that will now be returned by "Foo/get" on the
account records were copied to.
o created: "Id[Foo]|null"
A map of the creation id to an object containing any properties of
the copied Foo object that are set by the server (such as the "id"
in most object types; note, the id is likely to be different to
the id of the object in the account it was copied from).
This argument is null if no Foo objects were successfully copied.
o notCreated: "Id[SetError]|null"
A map of the creation id to a SetError object for each record that
failed to be copied, or null if none.
The SetError may be any of the standard set errors returned for a
create or update. In addition, the following SetError is defined:
"alreadyExists": The server forbids duplicates, and the record
already exists in the target account. An "existingId" property of
type "Id" MUST be included on the SetError object with the id of the
existing record.
The following additional errors may be returned instead of the "Foo/
copy" response:
"fromAccountNotFound": The "fromAccountId" does not correspond to a
valid account.
"fromAccountNotSupportedByMethod": The "fromAccountId" given
corresponds to a valid account, but the account does not support this
data type.
"stateMismatch": An "ifInState" argument was supplied and it does not
match the current state, or an "ifFromInState" argument was supplied
and it does not match the current state in the from account.
5.5. /query
For data sets where the total amount of data is expected to be very
small, clients can just fetch the complete set of data and then do
any sorting/filtering locally. However, for large data sets (e.g.,
multi-gigabyte mailboxes), the client needs to be able to
search/sort/window the data type on the server.
A query on the set of Foos in an account is made by calling "Foo/
query". This takes a number of arguments to determine which records
to include, how they should be sorted, and which part of the result
should be returned (the full list may be *very* long). The result is
returned as a list of Foo ids.
A call to "Foo/query" takes the following arguments:
o accountId: "Id"
The id of the account to use.
o filter: "FilterOperator|FilterCondition|null"
Determines the set of Foos returned in the results. If null, all
objects in the account of this type are included in the results.
A *FilterOperator* object has the following properties:
* operator: "String"
This MUST be one of the following strings:
+ "AND": All of the conditions must match for the filter to
match.
+ "OR": At least one of the conditions must match for the
filter to match.
+ "NOT": None of the conditions must match for the filter to
match.
* conditions: "(FilterOperator|FilterCondition)[]"
The conditions to evaluate against each record.
A *FilterCondition* is an "object" whose allowed properties and
semantics depend on the data type and is defined in the /query
method specification for that type. It MUST NOT have an
"operator" property.
o sort: "Comparator[]|null"
Lists the names of properties to compare between two Foo records,
and how to compare them, to determine which comes first in the
sort. If two Foo records have an identical value for the first
comparator, the next comparator will be considered, and so on. If
all comparators are the same (this includes the case where an
empty array or null is given as the "sort" argument), the sort
order is server dependent, but it MUST be stable between calls to
"Foo/query". A *Comparator* has the following properties:
* property: "String"
The name of the property on the Foo objects to compare.
* isAscending: "Boolean" (optional; default: true)
If true, sort in ascending order. If false, reverse the
comparator's results to sort in descending order.
* collation: "String" (optional; default is server-dependent)
The identifier, as registered in the collation registry defined
in [RFC4790], for the algorithm to use when comparing the order
of strings. The algorithms the server supports are advertised
in the capabilities object returned with the Session object
(see Section 2).
If omitted, the default algorithm is server dependent, but:
1. It MUST be unicode-aware.
2. It MAY be selected based on an Accept-Language header in
the request (as defined in [RFC7231], Section 5.3.5) or
out-of-band information about the user's language/locale.
3. It SHOULD be case insensitive where such a concept makes
sense for a language/locale. Where the user's language is
unknown, it is RECOMMENDED to follow the advice in
Section 5.2.3 of [RFC8264].
The "i;unicode-casemap" collation [RFC5051] and the Unicode
Collation Algorithm (<http://www.unicode.org/reports/tr10/>)
are two examples that fulfil these criterion and provide
reasonable behaviour for a large number of languages.
When the property being compared is not a string, the
"collation" property is ignored, and the following comparison
rules apply based on the type. In ascending order:
+ "Boolean": false comes before true.
+ "Number": A lower number comes before a higher number.
+ "Date"/"UTCDate": The earlier date comes first.
The Comparator object may also have additional properties as
required for specific sort operations defined in a type's /query
method.
o position: "Int" (default: 0)
The zero-based index of the first id in the full list of results
to return.
If a negative value is given, it is an offset from the end of the
list. Specifically, the negative value MUST be added to the total
number of results given the filter, and if still negative, it's
clamped to "0". This is now the zero-based index of the first id
to return.
If the index is greater than or equal to the total number of
objects in the results list, then the "ids" array in the response
will be empty, but this is not an error.
o anchor: "Id|null"
A Foo id. If supplied, the "position" argument is ignored. The
index of this id in the results will be used in combination with
the "anchorOffset" argument to determine the index of the first
result to return (see below for more details).
o anchorOffset: "Int" (default: 0)
The index of the first result to return relative to the index of
the anchor, if an anchor is given. This MAY be negative. For
example, "-1" means the Foo immediately preceding the anchor is
the first result in the list returned (see below for more
details).
o limit: "UnsignedInt|null"
The maximum number of results to return. If null, no limit
presumed. The server MAY choose to enforce a maximum "limit"
argument. In this case, if a greater value is given (or if it is
null), the limit is clamped to the maximum; the new limit is
returned with the response so the client is aware. If a negative
value is given, the call MUST be rejected with an
"invalidArguments" error.
o calculateTotal: "Boolean" (default: false)
Does the client wish to know the total number of results in the
query? This may be slow and expensive for servers to calculate,
particularly with complex filters, so clients should take care to
only request the total when needed.
If an "anchor" argument is given, the anchor is looked for in the
results after filtering and sorting. If found, the "anchorOffset" is
then added to its index. If the resulting index is now negative, it
is clamped to 0. This index is now used exactly as though it were
supplied as the "position" argument. If the anchor is not found, the
call is rejected with an "anchorNotFound" error.
If an "anchor" is specified, any position argument supplied by the
client MUST be ignored. If no "anchor" is supplied, any
"anchorOffset" argument MUST be ignored.
A client can use "anchor" instead of "position" to find the index of
an id within a large set of results.
The response has the following arguments:
o accountId: "Id"
The id of the account used for the call.
o queryState: "String"
A string encoding the current state of the query on the server.
This string MUST change if the results of the query (i.e., the
matching ids and their sort order) have changed. The queryState
string MAY change if something has changed on the server, which
means the results may have changed but the server doesn't know for
sure.
The queryState string only represents the ordered list of ids that
match the particular query (including its sort/filter). There is
no requirement for it to change if a property on an object
matching the query changes but the query results are unaffected
(indeed, it is more efficient if the queryState string does not
change in this case). The queryState string only has meaning when
compared to future responses to a query with the same type/sort/
filter or when used with /queryChanges to fetch changes.
Should a client receive back a response with a different
queryState string to a previous call, it MUST either throw away
the currently cached query and fetch it again (note, this does not
require fetching the records again, just the list of ids) or call
"Foo/queryChanges" to get the difference.
o canCalculateChanges: "Boolean"
This is true if the server supports calling "Foo/queryChanges"
with these "filter"/"sort" parameters. Note, this does not
guarantee that the "Foo/queryChanges" call will succeed, as it may
only be possible for a limited time afterwards due to server
internal implementation details.
o position: "UnsignedInt"
The zero-based index of the first result in the "ids" array within
the complete list of query results.
o ids: "Id[]"
The list of ids for each Foo in the query results, starting at the
index given by the "position" argument of this response and
continuing until it hits the end of the results or reaches the
"limit" number of ids. If "position" is >= "total", this MUST be
the empty list.
o total: "UnsignedInt" (only if requested)
The total number of Foos in the results (given the "filter").
This argument MUST be omitted if the "calculateTotal" request
argument is not true.
o limit: "UnsignedInt" (if set by the server)
The limit enforced by the server on the maximum number of results
to return. This is only returned if the server set a limit or
used a different limit than that given in the request.
The following additional errors may be returned instead of the "Foo/
query" response:
"anchorNotFound": An anchor argument was supplied, but it cannot be
found in the results of the query.
"unsupportedSort": The "sort" is syntactically valid, but it includes
a property the server does not support sorting on or a collation
method it does not recognise.
"unsupportedFilter": The "filter" is syntactically valid, but the
server cannot process it. If the filter was the result of a user's
search input, the client SHOULD suggest that the user simplify their
search.
5.6. /queryChanges
The "Foo/queryChanges" method allows a client to efficiently update the state of a cached query to match the new state on the server. It takes the following arguments: o accountId: "Id" The id of the account to use. o filter: "FilterOperator|FilterCondition|null" The filter argument that was used with "Foo/query". o sort: "Comparator[]|null" The sort argument that was used with "Foo/query". o sinceQueryState: "String" The current state of the query in the client. This is the string that was returned as the "queryState" argument in the "Foo/query" response with the same sort/filter. The server will return the changes made to the query since this state. o maxChanges: "UnsignedInt|null" The maximum number of changes to return in the response. See error descriptions below for more details. o upToId: "Id|null" The last (highest-index) id the client currently has cached from the query results. When there are a large number of results, in a common case, the client may have only downloaded and cached a small subset from the beginning of the results. If the sort and filter are both only on immutable properties, this allows the server to omit changes after this point in the results, which can significantly increase efficiency. If they are not immutable, this argument is ignored. o calculateTotal: "Boolean" (default: false) Does the client wish to know the total number of results now in the query? This may be slow and expensive for servers to calculate, particularly with complex filters, so clients should take care to only request the total when needed.
The response has the following arguments:
o accountId: "Id"
The id of the account used for the call.
o oldQueryState: "String"
This is the "sinceQueryState" argument echoed back; that is, the
state from which the server is returning changes.
o newQueryState: "String"
This is the state the query will be in after applying the set of
changes to the old state.
o total: "UnsignedInt" (only if requested)
The total number of Foos in the results (given the "filter").
This argument MUST be omitted if the "calculateTotal" request
argument is not true.
o removed: "Id[]"
The "id" for every Foo that was in the query results in the old
state and that is not in the results in the new state.
If the server cannot calculate this exactly, the server MAY return
the ids of extra Foos in addition that may have been in the old
results but are not in the new results.
If the sort and filter are both only on immutable properties and
an "upToId" is supplied and exists in the results, any ids that
were removed but have a higher index than "upToId" SHOULD be
omitted.
If the "filter" or "sort" includes a mutable property, the server
MUST include all Foos in the current results for which this
property may have changed. The position of these may have moved
in the results, so they must be reinserted by the client to ensure
its query cache is correct.
o added: "AddedItem[]"
The id and index in the query results (in the new state) for every
Foo that has been added to the results since the old state AND
every Foo in the current results that was included in the
"removed" array (due to a filter or sort based upon a mutable
property).
If the sort and filter are both only on immutable properties and
an "upToId" is supplied and exists in the results, any ids that
were added but have a higher index than "upToId" SHOULD be
omitted.
The array MUST be sorted in order of index, with the lowest index
first.
An *AddedItem* object has the following properties:
* id: "Id"
* index: "UnsignedInt"
The result of this is that if the client has a cached sparse array of
Foo ids corresponding to the results in the old state, then:
fooIds = [ "id1", "id2", null, null, "id3", "id4", null, null, null ]
If it *splices out* all ids in the removed array that it has in its
cached results, then:
removed = [ "id2", "id31", ... ];
fooIds => [ "id1", null, null, "id3", "id4", null, null, null ]
and *splices in* (one by one in order, starting with the lowest
index) all of the ids in the added array:
added = [{ id: "id5", index: 0, ... }];
fooIds => [ "id5", "id1", null, null, "id3", "id4", null, null, null ]
and *truncates* or *extends* to the new total length, then the
results will now be in the new state.
Note: splicing in adds the item at the given index, incrementing the
index of all items previously at that or a higher index. Splicing
out is the inverse, removing the item and decrementing the index of
every item after it in the array.
The following additional errors may be returned instead of the "Foo/ queryChanges" response: "tooManyChanges": There are more changes than the client's "maxChanges" argument. Each item in the removed or added array is considered to be one change. The client may retry with higher max changes or invalidate its cache of the query results. "cannotCalculateChanges": The server cannot calculate the changes from the queryState string given by the client, usually due to the client's state being too old. The client MUST invalidate its cache of the query results.5.7. Examples
Suppose we have a type *Todo* with the following properties: o id: "Id" (immutable; server-set) The id of the object. o title: "String" A brief summary of what is to be done. o keywords: "String[Boolean]" (default: {}) A set of keywords that apply to the Todo. The set is represented as an object, with the keys being the "keywords". The value for each key in the object MUST be true. (This format allows you to update an individual key using patch syntax rather than having to update the whole set of keywords as one, which a "String[]" representation would require.) o neuralNetworkTimeEstimation: "Number" (server-set) The title and keywords are fed into the server's state-of-the-art neural network to get an estimation of how long this Todo will take, in seconds. o subTodoIds: "Id[]|null" The ids of a list of other Todos to complete as part of this Todo. Suppose also that all the standard methods are defined for this type and the FilterCondition object supports a "hasKeyword" property to match Todos with the given keyword.
A client might want to display the list of Todos with either a
"music" keyword or a "video" keyword, so it makes the following
method call:
[[ "Todo/query", {
"accountId": "x",
"filter": {
"operator": "OR",
"conditions": [
{ "hasKeyword": "music" },
{ "hasKeyword": "video" }
]
},
"sort": [{ "property": "title" }],
"position": 0,
"limit": 10
}, "0" ],
[ "Todo/get", {
"accountId": "x",
"#ids": {
"resultOf": "0",
"name": "Todo/query",
"path": "/ids"
}
}, "1" ]]
This would query the server for the set of Todos with a keyword of
either "music" or "video", sorted by title, and limited to the first
10 results. It fetches the full object for each of these Todos using
back-references to reference the result of the query. The response
might look something like:
[[ "Todo/query", {
"accountId": "x",
"queryState": "y13213",
"canCalculateChanges": true,
"position": 0,
"ids": [ "a", "b", "c", "d", "e", "f", "g", "h", "i", "j" ]
}, "0" ],
[ "Todo/get", {
"accountId": "x",
"state": "10324",
"list": [{
"id": "a",
"title": "Practise Piano",
"keywords": {
"music": true,
"beethoven": true,
"mozart": true,
"liszt": true,
"rachmaninov": true
},
"neuralNetworkTimeEstimation": 3600
}, {
"id": "b",
"title": "Watch Daft Punk music video",
"keywords": {
"music": true,
"video": true,
"trance": true
},
"neuralNetworkTimeEstimation": 18000
},
...
]
}, "1" ]]
Now, suppose the user adds a keyword "chopin" and removes the keyword
"mozart" from the "Practise Piano" task. The client may send the
whole object to the server, as this is a valid PatchObject:
[[ "Todo/set", {
"accountId": "x",
"ifInState": "10324",
"update": {
"a": {
"id": "a",
"title": "Practise Piano",
"keywords": {
"music": true,
"beethoven": true,
"chopin": true,
"liszt": true,
"rachmaninov": true
},
"neuralNetworkTimeEstimation": 360
}
}
}, "0" ]]
or it may send a minimal patch:
[[ "Todo/set", {
"accountId": "x",
"ifInState": "10324",
"update": {
"a": {
"keywords/chopin": true,
"keywords/mozart": null
}
}
}, "0" ]]
The effect is exactly the same on the server in either case, and
presuming the server is still in state "10324", it will probably
return success:
[[ "Todo/set", {
"accountId": "x",
"oldState": "10324",
"newState": "10329",
"updated": {
"a": {
"neuralNetworkTimeEstimation": 5400
}
}
}, "0" ]]
The server changed the "neuralNetworkTimeEstimation" property on the
object as part of this change; as this changed in a way *not*
explicitly requested by the PatchObject sent to the server, it is
returned with the "updated" confirmation.
Let us now add a sub-Todo to our new "Practise Piano" Todo. In this
example, we can see the use of a reference to a creation id to allow
us to set a foreign key reference to a record created in the same
request:
[[ "Todo/set", {
"accountId": "x",
"create": {
"k15": {
"title": "Warm up with scales"
}
},
"update": {
"a": {
"subTodoIds": [ "#k15" ]
}
}
}, "0" ]]
Now, suppose another user deleted the "Listen to Daft Punk" Todo. The first user will receive a push notification (see Section 7) with the changed state string for the "Todo" type. Since the new string does not match its current state, it knows it needs to check for updates. It may make a request like: [[ "Todo/changes", { "accountId": "x", "sinceState": "10324", "maxChanges": 50 }, "0" ], [ "Todo/queryChanges", { "accountId": "x", "filter": { "operator": "OR", "conditions": [ { "hasKeyword": "music" }, { "hasKeyword": "video" } ] }, "sort": [{ "property": "title" }], "sinceQueryState": "y13213", "maxChanges": 50 }, "1" ]] and receive in response: [[ "Todo/changes", { "accountId": "x", "oldState": "10324", "newState": "871903", "hasMoreChanges": false, "created": [], "updated": [], "destroyed": ["b"] }, "0" ], [ "Todo/queryChanges", { "accountId": "x", "oldQueryState": "y13213", "newQueryState": "y13218", "removed": ["b"], "added": null }, "1" ]]
Suppose the user has access to another account "y", for example, a
team account shared between multiple users. To move an existing Todo
from account "x", the client would call:
[[ "Todo/copy", {
"fromAccountId": "x",
"accountId": "y",
"create": {
"k5122": {
"id": "a"
}
},
"onSuccessDestroyOriginal": true
}, "0" ]]
The server successfully copies the Todo to a new account (where it
receives a new id) and deletes the original. Due to the implicit
call to "Todo/set", there are two responses to the single method
call, both with the same method call id:
[[ "Todo/copy", {
"fromAccountId": "x",
"accountId": "y",
"created": {
"k5122": {
"id": "DAf97"
}
},
"oldState": "c1d64ecb038c",
"newState": "33844835152b"
}, "0" ],
[ "Todo/set", {
"accountId": "x",
"oldState": "871903",
"newState": "871909",
"destroyed": [ "a" ],
...
}, "0" ]]
5.8. Proxy Considerations
JMAP has been designed to allow an API endpoint to easily proxy through to one or more JMAP servers. This may be useful for load balancing, augmenting capabilities, or presenting a single endpoint to accounts hosted on different JMAP servers (splitting the request based on each method's "accountId" argument). The proxy need only understand the general structure of a JMAP Request object; it does not need to know anything specifically about the methods and arguments it will pass through to other servers. If splitting up the methods in a request to call them on different backend servers, the proxy must do two things to ensure back- references and creation-id references resolve the same as if the entire request were processed on a single server: 1. It must pass a "createdIds" property with each subrequest. If this is not given by the client, an empty object should be used for the first subrequest. The "createdIds" property of each subresponse should be passed on in the next subrequest. 2. It must resolve back-references to previous method results that were processed on a different server. This is a relatively simple syntactic substitution, described in Section 3.7. When splitting a request based on accountId, proxy implementors do need to be aware of "/copy" methods that copy between accounts. If the accounts are on different servers, the proxy will have to implement this functionality directly.
(page 58 continued on part 4)
