PRICKAR · API

Vad du kan göra

Allt som händer i prickar-systemet går genom det här API:et — panelen på väggen, ställningen på webben och adminverktyget är bara klienter. Det betyder att du kan bygga ditt eget: en väggskärm, en Slack-bot, en knapp på skrivbordet, ett skript. Allt är vanlig JSON över HTTPS från ….

Alla svar är JSON. Fel kommer alltid som {"error":"vad som gick fel"} med rimlig statuskod: 400 felaktig indata, 401 nyckel saknas/ogiltig, 404 finns inte, 409 krock, 429 för många anrop.

1 · Visa ställningen

Den öppna endpointen för displayer. Namn, antal prickar i år och personens id — sorterat med flest prickar först. Prickar räknas per kalenderår (§ 1.5.0), så första januari är alla på noll utan att någon behöver göra något.

Vill du ha förra årets ställning: lägg till ?year=2025. Endpointen (liksom /api/rules och /api/events) skickar Access-Control-Allow-Origin: *, så en sida på en annan adress kan läsa den direkt från webbläsaren.

2 · Följ live

Istället för att fråga om och om igen kan din klient hålla en anslutning öppen till /api/events och få en rad pushad varje gång något händer. Det är Server-Sent Events — webbläsare har det inbyggt (EventSource), och på en mikrokontroller räcker en HTTP-klient som läser rader löpande. Strömmen är öppen, ingen nyckel behövs.

ansluter till strömmen… — händelser som inträffar medan du har sidan öppen dyker upp här:

Var 25:e sekund kommer en kommentarsrad (: ping) som håller anslutningen vid liv genom proxies; retry: 3000 i början gör att EventSource återansluter själv om den tappas.

3 · Reglerna

Musikreglerna som JSON. Bara regler som handlar om själva spelandet kan ge prick (gives_prick: 1) — informationsregler som "första januari nollställs alla prickar" finns med men går inte att prickas för. Bygger du något som ska ge prickar: hämta med ?givesPrick=1 så får du bara de valbara.

4 · Ge en prick klientnyckel

Det anropet allt handlar om. Du behöver en klientnyckel (pk_…) från kommittén — skicka den i headern X-Api-Key. Personen anges med namn (skiftlägesokänsligt), så en fysisk knapp behöver bara veta vem den tillhör. Regelparagrafen är valfri men rekommenderad; det är den som ger pricken sammanhang.

Svar 201: {"id":42,"person":"Camilo","ruleParagraph":"1.10.0"} — och i samma ögonblick får alla som lyssnar på strömmen prick.added. Max 10 prickar per minut per IP-adress (429 därefter). givenBy är frivilligt men uppskattat — det syns i kommitténs logg.

5 · Överklaga en prick klientnyckel

Fick någon en prick på fel grunder? Överklaga den så hamnar den i kommitténs kö. Godkänns överklagan försvinner pricken (och prick.deleted pushas); avslås den står den kvar. En prick kan bara ha en väntande överklagan i taget.

1. Hitta pricken: GET /api/pricks?person_id=7 (person-id:t får du från ställningen)
2. Överklaga: POST /api/pricks/42/appeal med {"reason":"Det var dagens album och klockan var 14","appealedBy":"Camilo"}
3. Följ ärendet: GET /api/prick-appeals visar status pending → approved/rejected

6 · Föreslå en regel

Öppet för alla — inga nycklar. Förslaget hamnar i kö och blir regel först när kommittén godkänt det och gett det ett paragrafnummer. Max 5 förslag per minut per IP.

Bygga en egen knapp eller skärm?

Minsta möjliga klient som ger prick behöver: WiFi (2,4 GHz), en HTTPS-klient och en klientnyckel. Det är hela listan — panelen på väggen är i grunden exakt det, med en snygg display ovanpå. Några saker att veta:

• TLS: servern har ett Let's Encrypt-certifikat. På mikrokontroller: verifiera mot ISRG Root X1/X2, eller kör utan verifiering om du accepterar risken.
• Håll nyckeln hemlig: en läckt nyckel kan återkallas av kommittén utan att andra klienter påverkas — därför en nyckel per klient.
• Var snäll mot servern: hämta ställningen när en händelse kommer på strömmen, inte i en tight loop. Strömmen finns för att du ska slippa polla.
• Maskinläsbar spec: /openapi.yaml går att importera i Postman/Insomnia eller mata till en kodgenerator.

Referens: alla endpoints