Prickar

Kom igång

Allt är vanlig JSON över HTTP — bygg ditt gränssnitt i vad du vill. Bas-URL vid lokal körning: http://localhost:3210.

Autentisering: på kontorsnätet är API:et öppet. Kör servern över internet (REQUIRE_API_KEY=1) kräver alla /api-anrop en klientnyckel i X-Api-Key-headern (eller ?api_key= för EventSource, som inte kan sätta headers). Nycklar skapas och återkallas av kommittén på adminsidan — hela nyckeln visas bara en gång, vid skapandet. 401 = nyckel saknas/ogiltig.

Det viktigaste anropet, att ge någon en prick:

curl -X POST http://localhost:3210/api/pricks \
  -H 'Content-Type: application/json' \
  -d '{"personName":"Erik","ruleParagraph":"1.10.0","comment":"shufflade fredagslistan"}'

Samma sak från JavaScript:

await fetch('http://localhost:3210/api/pricks', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ personName: 'Erik', ruleParagraph: '1.10.0' }),
});

Maskinläsbar spec finns på /openapi.yaml — importera i Postman/Insomnia eller generera en klient.

Bra att veta

Säsonger: prickar räknas per kalenderår, så § 1.5.0 (nollställning 1 januari) sker automatiskt. Alla list-endpoints tar ?year=2025 för historik; utan parameter gäller innevarande år.
Prickgivande regler: bara regler om själva spelandet har gives_prick = 1 och kan användas som regelhänvisning. Informationsregler och upphävda regler avvisas med 400. Hämta valbara regler med GET /api/rules?givesPrick=1.
Enkla klienter: POST /api/pricks tar personName (skiftlägesokänsligt) istället för id — en fysisk knapp behöver bara kunna sitt namn.
Fel returneras alltid som {"error": "beskrivning"} med lämplig statuskod (400/404/409/500).

Personer & ställning

	Endpoint	Beskrivning
GET	`/api/persons`	Personer med pricksaldo, flest först. `?year=`
POST	`/api/persons`	Body: `{"name":"Erik"}`. 409 om namnet finns.
GET	`/api/scoreboard`	Slimmad ställning för displayer: bara namn + antal. `?year=`

Exempel: GET /api/scoreboard

{ "year": 2026, "scoreboard": [
  { "name": "Alexander", "pricks": 3 },
  { "name": "Erik", "pricks": 1 } ] }

	Endpoint	Beskrivning
GET	`/api/pricks`	Lista prickar, senaste först. `?year=`, `?person_id=`
POST	`/api/pricks`	Dela ut prick — se fält nedan.
DEL	`/api/pricks/:id`	Ta bort en prick.

POST /api/pricks — fält

Fält	Typ
`personId`	number	Ett av `personId`/`personName` krävs
`personName`	string	Skiftlägesokänslig namnmatchning
`ruleParagraph`	string	Valfri, t.ex. `"1.10.0"`. Måste ge prick.
`comment`	string	Valfri
`givenBy`	string	Valfri — vem som delade ut pricken

Svar 201: {"id":12,"person":"Erik","ruleParagraph":"1.10.0"} — och händelsen prick.added broadcastas (se Händelseström).

§ 1.12.2: vid bevisat tekniskt strul bör inga prickar delas ut. API:et kan inte bevisa strul åt dig — den bedömningen är din.

Regler

	Endpoint	Beskrivning
GET	`/api/rules`	Alla aktiva regler. `?givesPrick=1` för enbart prickgivande, `?includeRepealed=1` för att även få upphävda.

Exempel-regel

{ "id": 11, "paragraph": "1.10.0", "text": "Fredagslistan får inte shufflas",
  "revision": "1.0.5 - 2024-06-26", "repealed": 0, "gives_prick": 1 }

Regelförslag & överklaganden

Båda kräver manuellt kommittébeslut via /decision-endpointen.

	Endpoint	Beskrivning
GET	`/api/rule-suggestions`	Lista förslag med status.
POST	`/api/rule-suggestions`	`{"text":"...","suggestedBy":"..."}` → status `pending`.
POST	`/api/rule-suggestions/:id/decision`	`{"status":"approved","paragraph":"1.14.0"}` skriver in regeln (valfritt `"givesPrick":false`), eller `{"status":"rejected"}`.
GET	`/api/appeals`	Lista överklaganden med status.
POST	`/api/appeals`	`{"ruleParagraph":"1.6.0","reason":"...","appealedBy":"..."}`
POST	`/api/appeals/:id/decision`	`{"status":"approved"}` upphäver regeln (historiken behålls), eller `{"status":"rejected"}`.

Händelseström (realtid)

GET /api/events är en Server-Sent Events-ström. Bygger du en display eller något som ska reagera på prickar: lyssna här istället för att polla.

Event	Data
`prick.added`	`{ id, personId, person, ruleParagraph }`
`prick.deleted`	`{ id }`
`person.added`	`{ id, name }`
`rules.updated`	ny eller upphävd regel

const es = new EventSource('http://localhost:3210/api/events');
es.addEventListener('prick.added', (e) => {
  const prick = JSON.parse(e.data);
  console.log(prick.person + ' fick prick (§ ' + prick.ruleParagraph + ')');
});

Strömmen skickar en kommentarsrad (: ping) var 25:e sekund som heartbeat och retry: 3000 så att EventSource återansluter själv. På mikrokontroller (ESP32 m.fl.) räcker en vanlig HTTP-klient som håller anslutningen öppen och läser rader.