Skip to main content
Version: 0.1.0

allisall API

The allisall REST API. This document is its contract: the server and the allisall SDKs follow it.

Credentials​

Every /v1 operation takes a bearer token in Authorization: an API key (aia_, a key-id and a secret) or a dashboard session token, a JWT issued when the workspace owner signs in. Each operation declares its access policy in x-access:

  • KeyOnly: an API key holding scope. A session is refused with 401.
  • KeyOrSession: an API key holding scope, or a session.
  • SessionOnly: a session. Every key is refused with 403 session_required.
  • Public (/healthz) and ShareToken (/report).

Scopes are independent: ingest, read and write each grant only what they name.

Errors​

Every error is an RFC 9457 application/problem+json document. Its code comes from the catalogue in ErrorCode, and each code is sent with exactly one status, given as x-status. type is info.x-problem-type-base followed by the code. A 405 for a known path with another method carries Allow. It belongs to no operation, so no operation lists it.

Representation​

A response object includes every field its schema defines. A field with no value is null, except free text, which is "". Response enums are open: handle values not listed. A request body member the schema does not define is refused with unknown_field, and so is a query parameter the operation does not define. A query parameter sent empty (name=) or with leading or trailing whitespace is refused with invalid_format on that parameter: leave a parameter out to omit it. An integer query parameter is ASCII digits only; a sign is invalid_format. A query parameter sent more than once is refused with duplicate on that parameter, whether or not the values differ. A ; in the query outside a percent-escape is refused with invalid_format; send a literal semicolon as %3B. A query of more than 10,000 parameters, counting every &-separated pair, empty ones included, is refused with 414 uri_too_long. That is why every operation lists 414. A JSON request body is UTF-8: a charset parameter other than utf-8 (compared case-insensitively) is refused with 415, and an absent charset means UTF-8 (RFC 8259 §8.1). U+0000 is refused wherever a request carries text, because it cannot be stored: in any string of a JSON body, a map key or metadata member name included, in a query parameter value, and in a CSV import's file name. Each is invalid_format at its location; a CSV cell holding it refuses its row with invalid_format at its column, and a cursor holding it is refused as any altered cursor is. An id a request sends must be in the RFC 9562 string form, 8-4-4-4-12 hexadecimal digits in either case (UuidInput); any other spelling, such as 32 bare digits, urn:uuid: or braces, is invalid_format in a body or a query parameter, and 404 in a path. Ids in responses are lowercase (Uuid). Every 201 carries Location, the absolute path of the created resource's own read operation, such as /v1/clients/{id}. Instants are RFC 3339, in UTC in responses. Money is a JSON number in major units, with currency beside it.

Lists​

Every list returns {data, has_more, next_cursor} and takes limit (1 to 200, default 100) and cursor. Lists page forward only. x-list says what the cursor holds: a keyset position (keyset), which neither skips nor repeats a row when rows are inserted mid-walk, or an offset (offset). A keyset list can still show a row twice when its sort value changes mid-walk. No scheme short of a snapshot prevents that.

A list under a parent resource, such as /v1/clients/{id}/calculations, answers 404 not_found when the parent names nothing in the workspace, exactly as a read of the parent would. An empty data means the parent exists and has no children.

Operation extensions​

Each operation carries these extensions, which state how the server treats it:

  • x-access: the access policy and, for a key, the one scope it needs.
  • x-rate-limit-policy: the bucket a key request consumes: ingest for POST /v1/events (100 per second, burst 100), import for the two CSV import operations (one per 6 seconds, burst 10), or api for every other operation (10 per second, burst 600). It is unused unless a key acts. Sessions are not rate limited.
  • x-idempotent: true on the seven creating operations that take Idempotency-Key.
  • x-body-limit: the request body limit, on operations that take a body. The units are decimal: 1M is 1,000,000 bytes, not 1 MiB, and 5M and 26M scale the same way. A body of exactly the limit is accepted; a larger one is refused with 413 payload_too_large. An operation with no x-body-limit is still capped, at the 1M default (1,000,000 bytes), so a larger body gets the same 413. That is why every operation lists 413.
  • x-list: the cursor kind, on list operations.

Versioning​

/v1 is not yet declared stable. Until it is, it may still change incompatibly. Once it is stable, /v1 takes additive changes only. These changes are additive:

  • a new route;
  • a new optional request field or query parameter;
  • a new response field;
  • a new value of a response enum;
  • a new error code, or a new field-level code;
  • a new response header;
  • a change to detail wording;
  • a change to the length or content of an opaque value, such as a cursor;
  • a change to RateLimit or RateLimit-Policy that follows the IETF draft.

A client stays compatible with every additive change when it does these:

  • ignore response fields it does not recognise;
  • handle response enum values it does not recognise;
  • handle error codes it does not recognise, by falling back on the HTTP status;
  • not depend on the order of fields in an object.

A deprecated operation is marked deprecated: true, and its responses carry Deprecation, Link and Sunset.

Authentication​

An API key: aia_, an 8-character key-id and a 43-character secret. Its scopes are listed in each operation's security requirement.

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

aia_ + 8-character key id + 43-character secret