replace big-tech and host basic infrastructure yourself! ordner.fyi
ordner docs developers compatibility.md
2.3 kB · 53 lines
Markdown
at main

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 using only 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/query sorts by id, /changes lists in no promised order, a query without sort in no promised order.
  • The form of ids, blob ids, states, tokens and the source id beyond what Concepts §3 says.
  • An access token's contents: it is opaque to the application.
  • The examples' exact descriptions (description of an error is for people); branch on type.

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.