curl -H "x-api-key: $SG_API_KEY" \
https://api.smart-gulvvarme.dk/v1/buildingsHver forespørgsel skal bære en API-nøgle i headeren x-api-key:
curl -H "x-api-key: $SG_API_KEY" \
https://api.smart-gulvvarme.dk/v1/buildingsNøglen opretter du selv på Min konto eller i appen under Indstillinger → API-nøgler. Den er bundet til dine egne bygninger, så du kan kun se og ændre det, du selv ejer — aldrig andres.
En nøgle bærer et sæt rettigheder:
| Rettighed | Giver adgang til |
|---|---|
buildings:read | At læse bygninger og rum |
buildings:write | At ændre indstillinger på et rum |
En nøgle med kun buildings:read får 403 på PATCH. Vælg "Læse og ændre" ved oprettelsen, hvis din integration skal kunne ændre temperaturer eller slukke for et rum.
Nøglen giver adgang til at styre varmen i en rigtig bolig. Læg den aldrig i kode, der sendes til en browser eller en app — hold den på en server, du selv kontrollerer, eller i et sted til hemmeligheder.
Er en nøgle kommet på afveje, spærrer du den samme sted, som du oprettede den — på websitet eller i appen. Alt der bruger nøglen holder op med at virke inden for et minut. Spærring kan ikke fortrydes — opret i stedet en ny.
Fejl har altid samme form, og HTTP-statuskoden fortæller, hvad der gik galt:
| Status | code | Betyder |
|---|---|---|
400 | invalid_argument | Kroppen kunne ikke godkendes — se message. Rammer også et felt, der ikke må skrives |
401 | unauthenticated | Der var ingen x-api-key-header |
403 | permission_denied | Nøglen er ukendt, spærret, eller mangler rettigheden |
404 | not_found | Findes ikke — eller er ikke dækket af din nøgle |
500 | internal | Fejl hos os |
Beder du om en bygning, der findes, men som din nøgle ikke dækker, får du 404 — ikke 403.
Det er med vilje. Et 403 ville afsløre, at netop det id eksisterer, og gøre det muligt at gætte sig frem til andres bygninger. Med 404 kan de to tilfælde ikke skelnes udefra.
Kald med rimelighed. Et poll-interval på 30-60 sekunder er rigeligt til at følge et hjem — temperaturer i en bolig ændrer sig langsomt, og sensorerne rapporterer ikke oftere.
Husk, at ét kald til /rooms giver dig alle rum med sensordata. Kald ikke rummene enkeltvis.
Læs videre
{
"error": {
"code": "not_found",
"message": "No such building: does-not-exist"
}
}