API-kontrakten

En bearer-API-nøgle

Alt andet. Nøglen opløses på serveren til en konto, et arbejdsområde, en rolle og et sæt verber. Læg den aldrig i en query-streng, i en fejlrapport eller i noget, der registrerer en URL.

authorization: Bearer mk_live_...

En session-cookie

Bruges af ruterne til oprettelse og log ind samt af de to kontoruter — den, der udsteder en kontos første master-nøgle, og den, der giver en browser dens CSRF-token. Det er browserens mekanisme, og det er den eneste vej til det endpoint, der udsteder den første nøgle, for før det kald findes der ingen nøgle at autentificere med.

CSRF-tokenet

Et kald, der ændrer tilstand og er autentificeret med en cookie, skal gentage sessionens token i en header, fordi en browser selv vedhæfter en cookie til et kald på tværs af sites. En kalder, der bruger en API-nøgle, har ikke brug for noget af dette: en browser vedhæfter aldrig en nøgle af sig selv, så en nøgle kan ikke bruges på tværs af sites.

GET  /api/v2/account/csrf-token   → { "csrf_token": "...", "header_name": "x-csrf-token" }
POST /api/v2/account/master-key   → x-csrf-token: <that token>

{
  "request_id": "23ba77f0c6474ccb8dc5d65d1a44d069",
  "data": { }
}

{
  "error": {
    "code": "version_conflict",
    "message": "…",
    "type": "invalid_request_error"
  }
}

API'et returnerer aldrig 200 ved en fejl. Er statussen 200, findes der et data-objekt, og findes der et error-objekt, siger statussen det også.

Forgren på koden, aldrig på beskeden. Vis aldrig en rå kode til et menneske — oversæt den til tekst, de kan handle på.

Læg request-id'et et sted, det kan kopieres fra, på enhver fejlskærm. Det er det første, support beder om, og tjenesten logger den samme værdi.

Næsten alt er POST.

Også læsninger. En læsning tager en body med filtre, og en nøgle hører hjemme i en header frem for i en URL, som proxyer og browserhistorik registrerer. De to task-endpoints er de eneste GET-kald. Behandl det ikke som en forglemmelse, der skal rettes.

Tidsstempler er unix-millisekunder.

Tretten cifre, mindst 1000000000000, i begge retninger. En værdi i sekunders præcision afvises frem for at blive læst som en dato i 1970.

En læsning navngiver præcis ét subjekt.

Visningen og søgningen tager hver ét subjekt-id, og det skal svare til hukommelsestypen: en forespørgsel på user navngiver et user_id, en forespørgsel på agent navngiver et agent_id. At sende begge fejler altid valideringen, så byg valget som en kontakt frem for to felter.

Bodies valideres strengt.

Et ukendt felt er en valideringsfejl, ikke noget, der stille ignoreres. Et stavet forkert navn fejler højlydt frem for at se ud til at virke — og intet felt, du kunne sende, navngiver overhovedet et arbejdsområde, et filter eller en embedding-version.