Onboarding Gids voor WeatherPro REST API met Swagger ======================================================= Welkom bij de WeatherPro API! Deze gids helpt je snel aan de slag te gaan met onze REST API, inclusief belangrijke concepten zoals OAuth 2.0, JSON Web Tokens (JWT), en paginering. Volg de stappen en gebruik de meegeleverde codevoorbeelden om efficiënt te starten. Inhoudsopgave ------------- 1. Toegang verkrijgen 2. Authenticatie met OAuth 2.0 en JWT 3. Gebruikersprofiel ophalen 4. Accountinstellingen bijwerken 5. Paginering gebruiken 6. Tips voor snelle integratie 1. Toegang verkrijgen --------------------- Stap 1: Registreer een applicatie - Ga naar de ontwikkelaarsconsole op [WeatherPro Developer Portal](https://developer.weatherpro.com). - Maak een nieuwe applicatie aan en verkrijg je client_id en client_secret. Stap 2: OAuth 2.0 Authorization Code Flow - Gebruik de OAuth 2.2-standaard voor autorisatie. - Redirect URI instellen tijdens registratie. 2. Authenticatie met OAuth 2.0 en JWT --------------------------------------- Stap 1: Verkrijg een access token Gebruik de client credentials om een access token te verkrijgen: ```bash curl -X POST https://api.weatherpro.com/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" ``` Stap 2: Gebruik het access token - Voeg het access token toe aan je API-verzoeken via de Authorization header: ```http Authorization: Bearer YOUR_ACCESS_TOKEN ``` Tip: Zorg dat je de token vervalt en vernieuwt volgens de OAuth 2.0 specificaties. 3. Gebruikersprofiel ophalen ----------------------------- Endpoint: `GET /users/me` Voorbeeld: ```bash curl -X GET https://api.weatherpro.com/users/me \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` Response voorbeeld: ```json { "id": "12345", "name": "Jan Jansen", "email": "jan.jansen@example.com", "location": "Amsterdam" } ``` Tip: Gebruik Swagger UI voor interactieve tests. Log in met je OAuth token. 4. Accountinstellingen bijwerken -------------------------------- Endpoint: `PUT /users/me/settings` Voorbeeld payload: ```json { "temperatureUnit": "Celsius", "language": "NL" } ``` Voorbeeld curl: ```bash curl -X PUT https://api.weatherpro.com/users/me/settings \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"temperatureUnit": "Celsius", "language": "NL"}' ``` Tip: Controleer de response op bevestiging en foutmeldingen. 5. Paginering gebruiken ----------------------- Bij endpoints die lijsten teruggeven, zoals weersvoorspellingen of gebruikersdata, wordt paginering toegepast. Voorbeeld: ophalen van een lijst met 10 items per pagina, eerste pagina: ```http GET /forecasts?page=1&limit=10 ``` Vervolgpagina: ```http GET /forecasts?page=2&limit=10 ``` Tip: Gebruik de `nextPage` URL uit de response metadata voor naadloos navigeren. 6. Tips voor snelle integratie ----------------------------- - Gebruik Swagger UI: Open de Swagger documentatie en test endpoints interactief. - Authenticeer eerst: Zorg dat je een geldig access token hebt voordat je API-aanvragen doet. - Lees de API-specificaties: Bekijk de Swagger JSON/YAML voor alle beschikbare endpoints en parameters. - Automatiseer token verversing: Implementeer een mechanisme om tokens automatisch te vernieuwen. - Documenteer je eigen gebruik: Houd bij welke endpoints je gebruikt en welke data je verstuurt. Veel succes met het integreren van WeatherPro API! Mocht je vragen hebben, neem gerust contact op via support@weatherpro.com.

Zeker! Hier is een complete onboardinggids voor je WeatherPro REST API documentatie met Swagger. # WeatherPro API Onboarding Gids 🌤️ Welkom bij de WeatherPro API! Deze gids helpt je snel aan de slag te gaan met onze weersvoorspellings-API. ## 📋 Vereisten - Basis kennis van REST APIs - HTTP-verzoeken (GET, POST, PUT) - JSON-formaat - OAuth 2.0 begrip ## 🔑 Authenticatie Stroom ### Stap 1: Client Registratie ```bash # Registreer je applicatie om credentials te krijgen POST /api/v1/clients/register { "name": "Jouw App Naam", "redirect_uri": "https://jouwapp.com/callback" } ``` Antwoord: ```json { "client_id": "uw_client_id_here", "client_secret": "uw_client_secret_here" } ``` ### Stap 2: Authorization Code Ophalen ```javascript // Redirect gebruikers naar authorization endpoint const authUrl = `https://api.weatherpro.com/oauth/authorize? client_id=UW_CLIENT_ID& redirect_uri=YOUR_REDIRECT_URI& response_type=code& scope=read_profile+update_settings`; window.location.href = authUrl; ``` ### Stap 3: Access Token Verkrijgen ```javascript // Wissel authorization code voor access token const response = await fetch('https://api.weatherpro.com/oauth/token', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', }, body: new URLSearchParams({ grant_type: 'authorization_code', code: 'AUTHORIZATION_CODE_FROM_STAP_2', redirect_uri: 'YOUR_REDIRECT_URI', client_id: 'UW_CLIENT_ID', client_secret: 'UW_CLIENT_SECRET' }) }); const tokens = await response.json(); // Bewaar het access token veilig const accessToken = tokens.access_token; ``` ## 🚀 Gebruiksscenario's ### Scenario 1: Gebruikersprofiel Ophalen ```javascript async function getUserProfile() { try { const response = await fetch('https://api.weatherpro.com/api/v1/users/profile', { method: 'GET', headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json' } }); if (!response.ok) throw new Error('Profiel ophalen mislukt'); const profile = await response.json(); console.log('Gebruikersprofiel:', profile); return profile; } catch (error) { console.error('Fout:', error); } } ``` Verwachte Response: ```json { "id": "user_123", "email": "gebruiker@example.com", "name": "Jan Jansen", "preferences": { "temperature_unit": "celsius", "language": "nl", "notifications_enabled": true }, "subscription_tier": "premium" } ``` ### Scenario 2: Accountinstellingen Bijwerken ```javascript async function updateUserSettings(newSettings) { try { const response = await fetch('https://api.weatherpro.com/api/v1/users/settings', { method: 'PUT', headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json' }, body: JSON.stringify(newSettings) }); if (!response.ok) throw new Error('Instellingen bijwerken mislukt'); const updatedSettings = await response.json(); console.log('Bijgewerkte instellingen:', updatedSettings); return updatedSettings; } catch (error) { console.error('Fout:', error); } } // Gebruik voorbeeld updateUserSettings({ "temperature_unit": "fahrenheit", "notifications_enabled": false }); ``` ## 📄 Paginering Begrijpen ### Paginering Parameters ```javascript // Haal tweede pagina met 25 items per pagina op const response = await fetch('https://api.weatherpro.com/api/v1/weather/history?page=2&limit=25', { headers: { 'Authorization': `Bearer ${accessToken}` } }); const data = await response.json(); console.log('Huidige pagina:', data.current_page); console.log('Totaal pagina\'s:', data.total_pages); console.log('Weergegeven items:', data.items); ``` Paginering Response Structuur: ```json { "data": [...], "pagination": { "current_page": 2, "total_pages": 10, "total_items": 245, "items_per_page": 25, "has_next": true, "has_previous": true } } ``` ## 🔄 Token Beheer ### Token Refresh Implementatie ```javascript let accessToken = 'huidig_token'; let refreshToken = 'jouw_refresh_token'; async function refreshAccessToken() { try { const response = await fetch('https://api.weatherpro.com/oauth/token', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', }, body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: refreshToken, client_id: 'UW_CLIENT_ID', client_secret: 'UW_CLIENT_SECRET' }) }); if (!response.ok) throw new Error('Token refresh mislukt'); const newTokens = await response.json(); accessToken = newTokens.access_token; refreshToken = newTokens.refresh_token; return accessToken; } catch (error) { console.error('Token refresh fout:', error); // Redirect naar login redirectToLogin(); } } // Automatische token refresh wrapper async function makeAuthenticatedRequest(url, options = {}) { let response = await fetch(url, { ...options, headers: { ...options.headers, 'Authorization': `Bearer ${accessToken}` } }); // Als token expired, refresh en probeer opnieuw if (response.status === 401) { await refreshAccessToken(); response = await fetch(url, { ...options, headers: { ...options.headers, 'Authorization': `Bearer ${accessToken}` } }); } return response; } ``` ## 💡 Best Practices & Tips ### 1. Error Handling ```javascript // Goede error handling async function apiCall() { try { const response = await makeAuthenticatedRequest('/api/endpoint'); if (response.status === 429) { console.warn('Rate limit bereikt, wacht even...'); await new Promise(resolve => setTimeout(resolve, 1000)); return apiCall(); // Retry } if (!response.ok) { throw new Error(`HTTP ${response.status}: ${await response.text()}`); } return await response.json(); } catch (error) { console.error('API call mislukt:', error); throw error; } } ``` ### 2. Rate Limiting - Maximaal 100 requests per minuut - Gebruik `Retry-After` header bij 429 responses - Implementeer exponential backoff voor retries ### 3. Veiligheid ```javascript // Veilig token management class TokenManager { constructor() { this.accessToken = null; this.refreshToken = null; } setTokens(tokens) { // Bewaar tokens veilig (niet in localStorage voor productie) this.accessToken = tokens.access_token; this.refreshToken = tokens.refresh_token; } clearTokens() { this.accessToken = null; this.refreshToken = null; } } ``` ## 🛠️ Snelstart Code Voorbeeld ```javascript // Complete implementatie voorbeeld class WeatherProClient { constructor(clientId, clientSecret) { this.clientId = clientId; this.clientSecret = clientSecret; this.baseURL = 'https://api.weatherpro.com'; this.tokenManager = new TokenManager(); } async getUserProfile() { return this.makeRequest('/api/v1/users/profile'); } async updateSettings(settings) { return this.makeRequest('/api/v1/users/settings', { method: 'PUT', body: JSON.stringify(settings) }); } async makeRequest(endpoint, options = {}) { const url = `${this.baseURL}${endpoint}`; const config = { headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${this.tokenManager.accessToken}` }, ...options }; let response = await fetch(url, config); if (response.status === 401) { await this.refreshTokens(); config.headers.Authorization = `Bearer ${this.tokenManager.accessToken}`; response = await fetch(url, config); } if (!response.ok) { throw new Error(`API Error: ${response.status}`); } return response.json(); } } ``` ## 📚 Volgende Stappen 1. **Test je implementatie** met onze sandbox environment 2. **Bekijk de volledige API docs** in Swagger UI 3. **Join onze community** voor support en updates 4. **Monitor je usage** in het developer dashboard ## 🆘 Ondersteuning - 📚 [Volledige Documentatie](https://docs.weatherpro.com) - 🐛 [Bug Reports](https://github.com/weatherpro/api-issues) - 💬 [Developer Community](https://community.weatherpro.com) - 📧 [Support Email](support@weatherpro.com) **Welkom bij het WeatherPro developer ecosysteem!** 🎉