Dit ben jij
volgt jou! Dat wil ik niet!
Jij volgt
Jij en zijn buddies
Wil je volgen?
Hieronder zie je de nieuwe versie van ValtAf.nl. Terug naar de oude website.   Meer informatie
Deelnemers Forum Webshop
Inloggen

Tutorial voor developers: koppelen met de Valtaf.nl / Slims.com API

Geschreven door Support op December 29, 2011

Met onze API kunnen programmeurs koppelingen met onze afslankservice tot stand brengen. Dit is bijvoorbeeld handig als je vanuit een andere applicatie direct het gewicht van een deelnemer wilt bijwerken, of als je vanuit een andere website direct het eetdagboek van iemand wilt aanpassen. Zo kan bijvoorbeeld een receptensite een link 'plaats dit recept in je eetdagboek op valtaf.nl of slims.com' bevatten. Zoiets kan met de API.

De mogelijkheden van onze API beperken zich natuurlijk niet alleen tot het bijwerken van het gewicht of het plaatsen van recepten. Je kunt het zo gek niet bedenken of het is mogelijk.

Hoe gaat dit in zijn werk? Om vanuit een andere applicatie of vanuit een andere website het dagboek van iemand bij te werken, moet je natuurlijk toegang hebben tot het account van die persoon. Om deze toegang te verkrijgen zou je kunnen vragen of zij haar wachtwoord aan jou wil afstaan, maar dat is natuurlijk niet de meest elegante manier. Om dit op een nettere en veel veiliger wijze te doen, maken wij gebruik van het OAuth protocol. Dit protocol werkt als volgt.

Veronderstel je hebt een receptenpagina, en op die receptenpagina - laten we die voor het gemak 'russischerecepten.nl' noemen - staat een link 'plaats dit recept in je eetdagboek op valtaf.nl of slims.com'. Zodra de bezoeker op die link klikt, wordt een pagina van valtaf.nl of slims.com geopend waarop duidelijk staat uitgelegd dat 'russischerecepten.nl' toestemming vraagt om het eetdagboek bij te werken. De bezoekster kan op deze pagina op de button 'ja, ik geef toestemming' of 'nee, ik geef geen toestemming' klikken. Nadat ze toestemming heeft gegeven keert ze terug naar russischerecepten.nl, en vanaf dat moment kan de receptensite in de achtergrond onze API aanroepen en het recept toevoegen aan het eetdagboek.

In dit artikel beschrijven we in woorden hoe de communicatie tussen een externe website en ons verloopt. Helemaal onderaan dit artikel vind je een link naar een voorbeeldscript waarin we het allemaal in PHP hebben geprogrammeerd. Als je zelf de koppeling in een andere taal dan PHP tot stand hebt gebracht, dan zouden we het leuk vinden als je je voorbeeldcode ook hier met ons zou willen delen.

Stap 1: je applicatie aanmelden
Om koppelingen met onze API tot stand te kunnen brengen, moet je eerst jouw applicatie bij ons aanmelden. Doordat alleen aangemelde en goedgekeurde applicaties toegang hebben tot onze API, kunnen we voorkomen dat onze servers overspoeld raken met API calls. Nadat je je applicatie hebt aangemeld, ontvang je van ons een 'consumer key' en een 'consumer secret'. Dit zijn jouw logingegevens waarmee je in het vervolg onze API kunt aanspreken.

Stap 2: een request token en toestemmingslink aanvragen
Laten we even voortbordueren op het voorbeeld van de receptenpagina. Op de receptenpagina staat een link om het recept in het dagboek van valtaf.nl of slims.com te plaatsen. Als een bezoeker op deze link klikt kunnen er twee dingen gebeuren. Als de deelnemer in het verleden al eerder toestemming heeft gegeven om recepten in het eetdagboek te plaatsen, dan kan de receptenpagina direct doorgaan naar stap 4 en meteen onze API aanroepen om het recept in het dagboek te plaatsen. Maar als de deelnemer nog niet eerder toestemming heeft gegeven, wordt de bezoeker eerst doorverwijzen naar onze pagina waar zij deze toestemming kan verstrekken. Dit laatste gaan we nu doen.

Om de deelnemer te kunnen doorverwijzen heb je een zogenaamd request token en een request secret nodig, en natuurlijk het adres van onze pagina waar je de deelnemer naar toe moet doorsturen. Deze gegevens vraag je op door via het OAuth protocol bij ons de pagina https://www.valtaf.nl/api/request-token of https://www.slims.com/api/request-token op te vragen. Als je een request token aanvraagt, geef je ook meteen het adres van een pagina op jouw website mee waar de gebruiker naartoe wordt terugverwezen nadat ze toestemming heeft gegeven, jouw welcome-back pagina.

Nadat je de hierboven besproken gegevens hebt opgevraagd, ontvang je het request token, het request secret en een link naar de pagina om de toestemming te verstrekken. Dit token en secret moet je even onthouden door het bijvoorbeeld in de sessie van de bezoeker op te slaan. Daarna stuur je de deelnemer door naar onze pagina, bijvoorbeeld door een 'location:' header te gebruiken. Voordat je de gebruiker doorstuurt, moet je wel even een variabele aan de URL toevoegen waarin het request token staat. Nadat de bezoeker is doorverwezen kan ze op onze pagina de toestemming verstrekken.

Stap 3: een access token aanvragen
Als de bezoeker terugkeert op jouw pagina, heeft ze toestemming gegeven. Maar voordat je de API kunt aanroepen heb je eerst een access token nodig. Het request token van stap 2 was namelijk maar een tijdelijk token dat alleen gebruikt kan worden om de toestemming aan te vragen, en niet voor het doen van daadwerkelijke calls naar onze API. Dit tijdelijke token moet je dus omzetten naar een definitief access token. Hiervoor moet je een nieuwe OAuth call naar onze API doen, en wel naar de pagina https://www.valtaf.nl/api/access-token of https://www.slims.com/api/access-token. Met deze call stuur je ook het request token en request secret mee dat je had ontvangen in stap 2. Als het goed is had je deze gegevens opgeslagen in de sessie van de deelnemer - dus die kun je gewoon weer uitlezen zodra de deelnemer terugkeert op jouw pagina.

Ook geef je een verifier mee als je het access token opvraagt. Deze verifier is als variabele toegevoegd aan het adres van jouw welcome-back pagina. Dus als jouw welcome-back pagina het adres www.russischerecepten.nl/welkom_terug is, dan sturen wij de deelnemer terug naar www.russischerecepten.nl/welkom_terug?oauth_verifier=abcdefg - waarbij de verifier natuurlijk voor iedereen anders is. Deze parameter kun je uitlezen en toevoegen aan de call.

Je ontvangt een access token en een access secret. Met deze gegevens kun je vervolgens calls naar onze API doen. Deze gegevens blijven geldig net zo lang totdat de deelnemer de verstrekte toegang weer intrekt. Het is daarom verstandig om ze in een database op te slaan, zodat je in de toekomst er opnieuw gebruik van kunt maken. Als de bezoeker bijvoorbeeld volgende week of volgende maand opnieuw op een linkje klikt om een recept in het dagboek te plaatsen, dan hoeft zij dus niet opnieuw toestemming te verlenen, maar kan het recept direct worden geplaatst.

Stap 4: het doen van API calls
Nadat je een access token en access secret hebt ontvangen, kun je API calls gaan doen. Momenteel is deze API nog in ontwikkeling. In een later stadium zullen we API calls gaan toevoegen. Ons streven is om alle functies van de website ook via de API toegankelijk te maken. Heb je bepaalde wensen voor API calls, features die je graag als eerste wilt laten toevoegen, dan kun je onder dit artikel je reactie plaatsen.
Bestanden:
Deze pagina is al meer dan vier weken geleden aangemaakt.

Nog geen lid?

Meld je nu gratis aan om ook af te vallen of om onze afvallers bij te staan

Heb jij ook Twitter?

Deel dit artikel

LinkedInFacebookGoogle+

Rubrieken

Trefwoorden