Felkontraktet

Det farligaste svaret ett API kan ge är 200 OK med en tom lista. Det betyder två helt olika saker — *"jag frågade och världen är tom"* och *"min fråga gick aldrig fram"* — och det säger dem med exakt samma ord. Vi har mätt femton varianter av det felet i våra egna källor och byggt det här kontraktet för att slippa skicka det vidare.

Regel 1: tomt är ett besked, inte ett fel

Går frågan fram och svaret är tomt får du 200 och en tom lista. Går frågan inte fram får du 502 eller 503 med ett skal-fält i klartext. En backend som inte svarar blir aldrig en tom lista hos dig.

Regel 2: null betyder omätt, aldrig noll

"spridning": {
  "traffar": 0, "kommuner": 0,
  "entydig": null,
  "skal": "frågan matchar inget ortnamn — spridningen är OMÄTT för den här frågan"
}

entydig: null betyder att frågan inte gick att mäta (en gatuadress är inget ortnamn). Behandla det aldrig som true. Får du inte peka fel: kräv entydig === true, annars fråga användaren.

Samma regel gäller hojd_m: null med nodata: true (ingen höjddata i punkten — inte havsnivå) och swing: null i valresultaten (distriktet får inte jämföras — inte noll förändring).

Regel 3: ett tak är inte ett antal

antal är hur många rader du fick. total (ortnamn) och antal_i_fonstret (avverkning) är hur många som finns, räknat före limiten, och avkortad/trunkerad säger att taket klippte.

Ett API som bara ger dig radantalet lär dig publicera limiten som ett resultat: fyra olika ortnamn gav alla exakt 50 träffar i vår egen mätning, för 50 var taket.

Regel 4: "inte svept" är okänt, inte noll

Register vi hämtar kommunvis bär ett tillståndsfält: kommunen_ar_svept, tillstand: "inlast". Är det falskt eller saknas är antalet okänt. Skriv inte "noll skyddsrum i kommunen" på ett svar som betyder att vi inte hämtat kommunen än — vi gjorde det misstaget själva, för 174 kommuner, och det är därför fältet finns.

Regel 5: en bild som inte kan fyllas levereras inte

/v1/render/vinjett svarar 503 med lagsta_fyllande_zoom när kartan inte kan täcka ytan, i stället för att skicka en bild med hål. Huvudet X-Fyllnad (0–1) säger hur stor del som fylldes.

Statuskoder