Compatibility #
1. What is stable #
The API is versioned by its capabilities. Within a capability URN —
https://ns.ordner.fyi/svc/jmap/files and
https://ns.ordner.fyi/svc/jmap/photos — nothing changes without
notice: every method, argument, property, condition, comparator, facet,
error type and limit this guide names keeps its meaning. A change that would
break an application is made under a new capability URN.
FileNode follows draft-ietf-jmap-filenode, revision 14, under the draft's
capability urn:ietf:params:jmap:filenode.
2. What may change, and how an application stays compatible #
Additions keep the capability:
- new methods, new optional arguments, new filter conditions and comparators, new built-in facets, new members in an answer, new capabilities and new members of a capability's value;
- new SetError and method error types, for new kinds of refusal;
- higher limits. The core limits are read from the session; an install may set them lower than this guide's numbers, never below what RFC 8620 requires.
So an application:
- ignores members it does not know, in every answer;
- treats an error type it does not know as the HTTP or JMAP class it comes in (a SetError as "not written", a method error as "the method failed");
- reads limits from the session, and the method limits of this guide as the most a call may hold;
- names in
usingonly the capabilities it uses; - never parses ids, blob ids or states.
3. What an application must not rely on #
- The order of a list the API does not sort:
FileVector/querysorts by id,/changeslists in no promised order, a query withoutsortin no promised order. - The form of ids, blob ids, states, tokens and the
sourceid beyond what Concepts §3 says. - An access token's contents: it is opaque to the application.
- The examples' exact descriptions (
descriptionof an error is for people); branch ontype.
4. How this guide is kept true #
Every example is a file the install's tests send to the server and compare with its answer, and every type's JSON Schema is generated from the constants the server checks with; a change that alters either fails the tests before it ships. What this guide says is what the server does.