Hoe werkt de authenticatie van de Davis v2 API?
Je hebt een gave Davis weerstation aan de muur hangen, en je wilt die waardevolle data – temperatuur, windsnelheid, neerslag – automatisch in je eigen systeem of app binnenhalen. Dan kom je uit bij de Davis v2 API.
Maar voordat je ook maar één datapunt kunt opvragen, moet je eerst langs de digitale deurwachter: authenticatie. Geen paniek, het is minder ingewikkeld dan het klinkt. Ik leg je precies uit hoe je die sleutel in handen krijgt en gebruikt, alsof we samen aan de keukentafel zitten.
Wat je nodig hebt voordat je begint
Voordat je ook maar één regel code aanraakt, moet je een paar dingen op een rijtje hebben. Zie het als je gereedschapskist voor je aan de klus begint.
Het belangrijkste is een actief Davis weerstation dat is aangesloten op het internet.
Dit kan via een WeatherLink Live-module (kost zo'n €150-€200) of een oudere WeatherLink IP-logger. Daarnaast heb je een account nodig op het WeatherLink-platform. Als je je station al hebt ingesteld in de WeatherLink-app, heb je dit waarschijnlijk al.
Zo niet, dan maak je die gratis aan. Zorg dat je de inloggegevens bij de hand hebt. Tot slot heb je een plek nodig om je API-sleutel veilig op te slaan – een notitie-app of wachtwoordmanager werkt prima.
Veelgemaakte fout: denken dat je API-sleutel hetzelfde is als je wachtwoord voor de app. Dat is niet zo. De sleutel is een aparte, lange reeks tekens die specifiek is voor API-toegang.
Stap 1: Je persoonlijke API-sleutel aanmaken
Dit is de meest cruciale stap. Je API-sleutel is als de unieke sleutel tot jouw weerstationdata.
Zonder deze sleutel staat de deur potdicht. Log in op de WeatherLink-website (niet de app) met je account. Ga naar je profiel- of accountinstellingen.
Daar zoek je naar een sectie met de naam "API" of "Developer".
Klik op "Nieuwe sleutel genereren" of iets vergelijkbaars. Het systeem zal nu twee belangrijke stukken informatie tonen: een API-sleutel (API Key) en een geheime sleutel (API Secret). De API-sleutel is openbaar en identificeert jou.
De geheime sleutel is als het wachtwoord bij die sleutel – die deel je met niemand. Kopieer beide waarden naar een veilige plek.
De geheime sleutel wordt vaak maar één keer volledig getoond. Tijdsindicatie: dit proces duurt hooguit 2 minuten.
De sleutels zijn direct actief.
Stap 2: De authenticatie-header opbouwen
De Davis v2 API gebruikt een methode genaamd "HMAC-SHA256" voor authenticatie. Ontdek hoe je de Davis WeatherLink API v2 gebruikt; het klinkt technisch, maar het betekent gewoon dat je een speciale handtekening maakt met je geheime sleutel.
Elke keer dat je de API aanroept, moet je deze handtekening meesturen in de HTTP-header van je verzoek. De handtekening is een hash die je maakt van drie dingen: je API-sleutel, de huidige tijd in seconden (een "timestamp"), en je geheime sleutel. De API verwacht de tijd in Unix-tijdformaat (het aantal seconden sinds 1 januari 1970). Let er bij het opvragen van data ook op hoe de API-limitatie werkt. Je kunt dit eenvoudig krijgen via een commando in je terminal of programmeertaal.
De exacte code hangt af van wat je gebruikt. In Python bijvoorbeeld, importeer je de 'hmac' en 'hashlib' modules.
Je combineert je API-sleutel en de timestamp tot een bericht, en gebruikt dan je geheime sleutel om daar de HMAC-SHA256-hash van te berekenen.
Het resultaat is een lange, onleesbare hexadecimale string – dat is je handtekening.
Stap 3: Het API-verzoek samenstellen en testen
Met je sleutel en handtekening op zak, is het tijd voor een testritje. De eenvoudigste manier om te testen is met een tool als cURL in je terminal.
Je bouwt een GET-verzoek naar het Davis API-eindpunt. Je moet drie dingen meesturen in de header: 'X-API-KEY' met je API-sleutel, 'X-API-SIGNATURE' met de zojuist gemaakte handtekening, en 'X-API-TIMESTAMP' met dezelfde Unix-timestamp die je voor de handtekening gebruikte. De timestamp mag niet meer dan 5 minuten afwijken van de servertijd van Davis – dit voorkomt dat iemand je verzoek onderschept en later opnieuw probeert te gebruiken.
Een basis cURL-commando ziet er zo uit (vervang de waarden tussen haakjes):
curl -H "X-API-KEY: [JOUW_API_SLEUTEL]" -H "X-API-SIGNATURE: [JOUW_HANDTEKENING]" -H "X-API-TIMESTAMP: [JOUW_TIMESTAMP]" https://api.weatherlink.com/v2/current/[JOUW_STATION_ID]
Als alles goed is, krijg je een JSON-antwoord terug met de huidige weergegevens. Dat is het moment dat je weet dat het werkt, en kun je bijvoorbeeld je eigen automatische weer-update op Twitter/X instellen!
Veelgemaakte valkuilen en hoe ze te omzeilen
De meeste beginners struikelen over dezelfde paar stenen. Ten eerste: de timestamp.
Als je systeemklok niet goed is gesynchroniseerd, wijkt je timestamp te veel af en weigert de API je verzoek. Los dit op door een NTP-service te gebruiken die je klok automatisch gelijk houdt. Ten tweede: het kopiëren van sleutels.
Een extra spatie aan het begin of einde van je API-sleutel of geheime sleutel zorgt voor een foutmelding.
Kopieer ze daarom rechtstreeks en plak ze in een schone teksteditor om spaties te controleren voordat je ze in je code gebruikt. Ten derde: de handtekening. De volgorde waarin je de API-sleutel en timestamp samenvoegt voor het hashen is cruciaal en staat in de documentatie.
Doe je dit verkeerd, dan is je handtekening ongeldig. Begin altijd met een werkend voorbeeld en pas het daarna stap voor stap aan.
Verificatie-checklist: ben je klaar?
Voordat je je integratie helemaal gaat bouwen, loop deze checklist na. Zo weet je zeker dat je basis staat als een huis.
- Account en station: Je hebt een actief WeatherLink-account en je Davis station is online en zichtbaar in de app/website.
- API-sleutels: Je hebt zowel de API Key (publiek) als de API Secret (geheim) veilig opgeslagen.
- Tijdssynchronisatie: De klok van je computer of server is gesynchroniseerd met een NTP-server.
- Eerste test: Je hebt een succesvolle test gedaan met cURL of een vergelijkbaar tool en je hebt de JSON-data met weergegevens ontvangen.
- Foutafhandeling: Je weet wat de foutmeldingen '401 Unauthorized' (foute sleutel/handtekening) en '403 Forbidden' (geen toegang tot dit station) betekenen.
Lukt het testen niet? Controleer dan eerst je timestamp en de opmaak van je handtekening. Dat zijn de twee meest voorkomende boosdoeners.
Als het dan nog niet werkt, is het tijd om de officiële documentatie erbij te pakken – die is gelukkig best helder. Zie je, het is vooral een kwestie van de juiste sleutel op de juiste plek zetten. Eenmaal geauthenticeerd, staat de hele wereld van jouw persoonlijke weerdata voor je open. Veel bouwplezier!