replace big-tech and host basic infrastructure yourself! ordner.fyi
11 kB · 252 lines
Markdown
at main

JMAP for this API #

JMAP (RFC 8620) is a JSON protocol over HTTPS: one session document, one API URL that takes a batch of method calls, and URLs for uploads, downloads and push. This chapter says as much of it as an application of this API needs; RFC 8620 says the rest. Files are the FileNode type of draft-ietf-jmap-filenode (revision 14); everything else is the install's own, under two capabilities.

1. The session #

GET <origin>/.well-known/jmap with the access token, following the redirect. The example shows the parts an application uses; the document holds more.

GET /jmap/session HTTP/1.1
Authorization: Bearer ${accessToken}
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

{
  "capabilities": {
    "urn:ietf:params:jmap:core": {
      "maxSizeUpload": 536870912,
      "maxConcurrentUpload": 16,
      "maxSizeRequest": 10000000,
      "maxConcurrentRequests": 48,
      "maxCallsInRequest": 16,
      "maxObjectsInGet": 500,
      "maxObjectsInSet": 500,
      "collationAlgorithms": [
        "i;ascii-numeric",
        "i;ascii-casemap",
        "i;unicode-casemap"
      ]
    },
    "urn:ietf:params:jmap:filenode": {},
    "https://ns.ordner.fyi/svc/jmap/files": {},
    "https://ns.ordner.fyi/svc/jmap/photos": {}
  },
  "accounts": {
    "${accountId}": {
      "name": "pip@ordner.example",
      "isPersonal": true,
      "isReadOnly": false,
      "accountCapabilities": {
        "urn:ietf:params:jmap:filenode": {
          "maxFileNodeDepth": 256,
          "maxSizeFileNodeName": 255,
          "mayCreateTopLevelFileNode": false
        },
        "https://ns.ordner.fyi/svc/jmap/photos": {
          "mayRender": false
        }
      }
    }
  },
  "primaryAccounts": {
    "urn:ietf:params:jmap:filenode": "${accountId}",
    "https://ns.ordner.fyi/svc/jmap/photos": "${accountId}",
    "urn:ietf:params:jmap:blob": "${accountId}",
    "urn:ietf:params:jmap:quota": "${accountId}"
  },
  "username": "pip@ordner.example",
  "apiUrl": "${apiUrl}",
  "downloadUrl": "${downloadUrl}",
  "uploadUrl": "${uploadUrl}",
  "eventSourceUrl": "${eventSourceUrl}",
  "state": "${*}"
}
  • capabilities lists what the install offers. This API is urn:ietf:params:jmap:core, urn:ietf:params:jmap:filenode (FileNode), https://ns.ordner.fyi/svc/jmap/files (annotations, fields, views, vectors, sources, facets) and https://ns.ordner.fyi/svc/jmap/photos (the photo value, faces, people, album suggestions). Their values are {} today. urn:ietf:params:jmap:blob and urn:ietf:params:jmap:quota are there too when the install hosts blobs.
  • accounts are the drives the credential reaches: the person's own (isPersonal: true) and each drive delegated to them. isReadOnly is false where the credential may write anything there, annotations included. Each account's accountCapabilities say what it supports; mayCreateTopLevelFileNode is true only with drive:write.
  • primaryAccounts["urn:ietf:params:jmap:filenode"] is the person's own drive.
  • apiUrl, uploadUrl, downloadUrl, eventSourceUrl are absolute URLs on the install (RFC 6570 level-1 templates): …/jmap/api, …/jmap/upload/{accountId}, …/jmap/download/{accountId}/{blobId}/{name}?type={type}, …/jmap/eventsource?types={types}&closeafter={closeafter}&ping={ping}. (The examples run against the files service directly, which answers them relative.)
  • state changes when the session does (a delegation accepted, a capability added): every API answer carries sessionState; when it differs from the session's, fetch the session again.

2. A request #

POST to apiUrl with Content-Type: application/json:

{
  "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:filenode",
            "https://ns.ordner.fyi/svc/jmap/files"],
  "methodCalls": [
    ["FileNode/query", { "accountId": "…", "filter": { "isAnnotated": false } }, "q"],
    ["FileNode/get", { "accountId": "…",
      "#ids": { "resultOf": "q", "name": "FileNode/query", "path": "/ids" } }, "g"]
  ]
}
  • using names every capability whose methods the request calls. A method of a capability not named is unknownMethod.
  • Each call is [name, arguments, callId]; the answer holds one or more [name, arguments, callId] per call, in order, with the same callId. A method that fails answers ["error", { "type", "description" }, callId] and the others still run.
  • A back-reference ("#ids": { "resultOf", "name", "path" }) takes an argument from an earlier answer in the same request (RFC 8620 §3.7): a query and the reading of what it found are one round trip.
  • At most maxCallsInRequest calls per request; at most maxObjectsInGet ids per /get and maxObjectsInSet objects per /set unless the method says less (§5).

3. The standard methods #

Every type of this API follows RFC 8620 §5 where it has the method:

Method Arguments Answer
T/get accountId, ids (or null: all, where allowed), properties state, list, notFound
T/changes accountId, sinceState, maxChanges oldState, newState, hasMoreChanges, created, updated, destroyed
T/set accountId, ifInState, create, update, destroy oldState, newState, created, updated, destroyed, notCreated, notUpdated, notDestroyed
T/query accountId, filter, sort, position or anchor and anchorOffset, limit, calculateTotal queryState, canCalculateChanges, position, ids, total, limit
T/queryChanges accountId, sinceQueryState, … added, removed
  • A /set that refuses one object answers a SetError for it in notCreated, notUpdated or notDestroyed ({ type, description, properties }); the rest are written. An update answer is null or the server-set values that changed.
  • /changes answers cannotCalculateChanges when it can no longer say what changed since that state; the application then reads again (Keeping up §3).
  • A /query window is RFC 8620 §5.5's: a negative position counts from the end, an anchor replaces the position and anchorOffset may be negative, a page past the end is empty, and a malformed argument is invalidArguments. Where the server caps a page or sets its size when the request gives none, it answers that as limit.
  • A maxChanges that is not a positive integer is invalidArguments, even where nothing changed.
  • States are opaque strings: compare them for equality, never order them.

4. Upload, download and push #

Upload (RFC 8620 §6.1): POST the bytes to uploadUrl with their Content-Type. The answer is 201 with { accountId, blobId, type, size }. The blob id is used in a /set (a file's content, an annotation's text) within the same session; an upload nobody uses is removed later.

POST /jmap/upload/${accountId} HTTP/1.1
Authorization: Bearer ${accessToken}
Content-Type: text/plain; charset=utf-8

INVOICE
Hansen Boat Yard
Hull cleaning and antifouling
Total 249.90 EUR, due 15 November 2026
HTTP/1.1 201 Created
content-type: application/json; charset=utf-8

{
  "accountId": "${accountId}",
  "blobId": "${invoiceText}",
  "type": "text/plain; charset=utf-8",
  "size": 93
}

Download (RFC 8620 §6.2): GET downloadUrl with accountId, blobId, a file name and the type to answer with. The answer is the bytes, as an attachment, with X-Content-Type-Options: nosniff; a script type is answered as application/octet-stream. One byte range is served (206), so a large file can be read in parts or resumed. A file's content blob id (FileNode.blobId) is bound to the person who read it: download it with a credential of the same person.

GET /jmap/download/${accountId}/${invoiceTextBlobId}/invoice.txt?type=text/plain HTTP/1.1
Authorization: Bearer ${accessToken}
HTTP/1.1 200 OK
content-type: text/plain
content-disposition: attachment; filename="invoice.txt"; filename*=UTF-8''invoice.txt

INVOICE
Hansen Boat Yard
Hull cleaning and antifouling
Total 249.90 EUR, due 15 November 2026

Push (RFC 8620 §7.3): GET eventSourceUrl with types (comma separated, or *), closeafter (state or no) and ping (seconds, held to 30–300; 0 for none), with the same Authorization header. The stream answers text/event-stream; each state event's data is a StateChange: per account, the types whose state moved. See Keeping up §5.

5. Capabilities and limits #

Limit Value Where
maxCallsInRequest 16 session (core)
maxObjectsInGet 500 session (core); FileNode/get and /query hold to it
maxObjectsInSet 500 session (core); methods below say less
maxSizeRequest 10,000,000 bytes session (core)
maxConcurrentRequests 48 per person session (core)
maxSizeUpload 536,870,912 bytes (files); the session answers the lowest of the install's services session (core)
maxConcurrentUpload 16 session (core)
EventSource streams a few per credential; more is 429 —
FileAnnotation/set 256 updates and destroys per call —
FileVector/set 256 per call; 4 vectors per file per source —
FileVector/get 500 ids —
AnnotationView/set 64 per call; 50 views per source —
AlbumSuggestion/set 256 per call; 200 pending per source —
AlbumSuggestion/get 500 ids —
PhotoFace/get 500 ids —
PhotoPeople/set 500 pictures per call —
PhotoFace/set 1,000 embeddings per call —
AppData/destroy 256 annotations per call —
FileNode/facets 10 facets, 100 values each —

Read the core limits from the session rather than from this table: the session answers the lowest value among the install's services, and an install may lower them. The per-method limits are the server's constants; the Reference gives every other one (lengths, counts, dimensions), and the JSON Schema carries them too.