Koppelingen tussen systemen klinken ingewikkeld. In de praktijk komt het neer op iets heel simpels. Je stuurt een vraag naar een adres en je krijgt een antwoord terug. Dat adres heet een endpoint. Wie dat eenmaal doorheeft, snapt ineens waar het over gaat.
Waar het misgaat is zelden de techniek. Het gaat mis bij verkeerde verwachtingen over wat zo’n adres wel en niet kan.
Bij Park Eifel speelde dat concreet. Ik bouwde daar een website met een boekingssysteem. De beschikbaarheid van accommodaties moest kloppen, elke dag opnieuw.
Die gegevens komen van een extern systeem, via een vast adres. Ik heb dat verzoek niet bij elk bezoek laten uitvoeren, maar periodiek. De bezoeker krijgt daardoor direct antwoord, ook als de andere partij even traag is.
Een endpoint is het loket waar je je verzoek indient.
Wat is een endpoint?
Een endpoint is een webadres waar je een verzoek naartoe stuurt. Het hoort bij een API en het is het punt waar jij binnenkomt.
Elk API-adres doet een ding. Het ene geeft je een lijst met producten. Het andere maakt een nieuwe boeking aan. Het derde vraagt de status van een betaling op.
Het verschil met een gewone webpagina
Beide zijn een adres, maar wat je terugkrijgt verschilt. Een pagina geeft je opmaak die een mens kan lezen. Een endpoint geeft je kale gegevens, meestal in JSON.
Hoe een verzoek eruitziet
Bij het verzoek versturen geef je drie dingen mee. Het adres zelf, de methode en meestal een sleutel.
De methode zegt wat je wilt. Ophalen, aanmaken, wijzigen of verwijderen. Dat onderscheid voorkomt dat je per ongeluk iets aanpast terwijl je alleen wilde kijken.
Sleutels en toegang
Bijna elk endpoint vraagt om authenticatie. Zonder sleutel krijg je geen antwoord. Zo weet de andere partij wie er aanklopt en wat die persoon mag zien.
De foutcodes die je gaat tegenkomen
Je hoeft niet alle foutcodes uit je hoofd te kennen. Vier komen er telkens terug.
Wat de belangrijkste betekenen
200: gelukt, je krijgt je gegevens.
401 of 403: je sleutel klopt niet of je mag dit niet zien.
404: dit adres bestaat niet, controleer je schrijfwijze.
429: je vraagt te vaak, wacht even.
500: er gaat iets mis aan de andere kant, niet bij jou.
Die laatste is belangrijk om te herkennen. Bij een 500 hoef je niet in je eigen code te zoeken.
Waarom je site er traag van wordt
Dit is de meest gemaakte fout. Je haalt bij elk bezoek live gegevens op. Je pagina wacht dan op een server die jij niet beheert.
Is die traag, dan is jouw site traag. Ligt hij eruit, dan hangt jouw pagina. Ik zet daarom altijd een tussenlaag met cache ertussen.
Voorraadstanden ververs ik per kwartier. Openingstijden een keer per dag. Alleen bij een boeking of betaling wil je echt live gegevens. Zet daar dan een korte wachttijd op.
Zelf aan de slag
Begin met het documentatie lezen van de partij waarmee je koppelt. Daar staat welk adres bij welke functie hoort en wat je precies terugkrijgt.
Test daarna handmatig voordat je iets bouwt. Zo weet je of het probleem bij jou of bij hen zit. Het backend van je site hoeft dan alleen nog te verwerken.
Ook WordPress heeft zulke adressen ingebouwd. Daarmee kun je berichten en pagina’s opvragen zonder de site zelf te openen. Dat controleer ik bij onderhoud. Een open adres is namelijk soms meer open dan bedoeld.
Wat je vastlegt per koppeling
Noteer welk adres je gebruikt en welke versie erbij hoort. Leveranciers brengen nieuwe versies uit en zetten oude na verloop van tijd uit.
Zet er ook bij wat er misgaat als de koppeling stopt. Blijft je site gewoon werken, of komt er een lege pagina? Dat antwoord bepaalt hoe snel je moet ingrijpen.
Bouw een terugvaloptie in
Ik laat een site altijd de laatst bekende gegevens tonen als een adres niet reageert. Dan staat er iets ouds in plaats van niets. Voor een bezoeker is dat het verschil tussen werkt en stuk.
Meer vragen over Endpoint
Dit zijn de vragen die ik hierover het vaakst krijg. Ik werk ze los uit.
Wat is een endpoint?
Hoe vind je het juiste endpoint van een dienst?
Wat betekenen de foutcodes bij een endpoint?
Hoe beveilig je een endpoint?
Wat is het verschil tussen een endpoint en een gewone URL?
Waarom reageert mijn endpoint traag?
Wat is een endpoint?
In de documentatie van de partij waarmee je koppelt. Bijna elke dienst heeft daar een aparte sectie voor op zijn website.
Daar staat welk adres bij welke functie hoort, wat je moet meesturen en wat je terugkrijgt. Vaak staat er ook een voorbeeld bij dat je kunt overnemen.
Is die documentatie er niet, dan is dat een waarschuwing op zichzelf. Een koppeling bouwen zonder handleiding kost al snel het dubbele aan uren, en je weet niet of het morgen nog werkt.
Vraag daarom altijd vooraf om de documentatie. Kan de leverancier die niet leveren, reken dan op flink meerwerk.
Test daarna een verzoek met de hand voordat je iets bouwt. Dan weet je zeker dat het adres werkt en dat je sleutel klopt. Dat scheelt uren zoeken in je eigen code.
Kijk ook of de leverancier een testomgeving aanbiedt. Kun je daar oefenen zonder echte boekingen aan te maken, dan scheelt dat een hoop risico bij de bouw.
Hoe vind je het juiste endpoint van een dienst?
Een endpoint is een webadres waar je een verzoek naartoe stuurt. Het hoort bij een API en het is het punt waar jij binnenkomt.
Elk endpoint doet precies een ding. Het ene geeft je een lijst met producten. Het andere maakt een nieuwe boeking aan. Het derde vraagt de status van een betaling op.
Je kunt het zien als een loket in een gemeentehuis. Je gaat naar het juiste loket met de juiste papieren en je krijgt antwoord. Ga je naar het verkeerde loket, dan sturen ze je weg.
Het verschil met een gewone webpagina zit in wat je terugkrijgt. Een pagina geeft opmaak die een mens kan lezen. Een endpoint geeft kale gegevens die een computer verwerkt.
Je hoeft dit niet zelf te kunnen bouwen om er profijt van te hebben. Het helpt al als je weet dat elke koppeling uit zulke adressen bestaat. Meer daarover lees je bij API.
Vraag bij een offerte voor een koppeling altijd welke endpoints er gebruikt worden. Je hoeft de techniek niet te begrijpen, maar dat antwoord zegt veel over hoe goed iemand het heeft uitgezocht.
Wat betekenen de foutcodes bij een endpoint?
Je hoeft ze niet allemaal uit je hoofd te kennen. Vijf komen er telkens terug en die verklaren bijna alles.
Code 200 betekent gelukt, je krijgt je gegevens. Code 401 of 403 betekent dat je sleutel niet klopt of dat je dit niet mag zien. Code 404 betekent dat dit adres niet bestaat, dus controleer je schrijfwijze.
Code 429 betekent dat je te vaak vraagt en even moet wachten. Dat gebeurt als je bijvoorbeeld bij elk bezoek gegevens ophaalt.
En code 500 betekent dat er iets misgaat aan de andere kant. Die laatste is belangrijk om te herkennen, want dan hoef je niet in je eigen code te zoeken.
Log fouten altijd, ook als alles werkt. Zo zie je patronen voordat er echt iets stukgaat en weet je bij een storing meteen waar je moet kijken.
Zorg dat fouten ergens binnenkomen waar iemand ze leest. Een logbestand dat niemand opent, is hetzelfde als geen logbestand hebben.
Hoe beveilig je een endpoint?
Een endpoint is een deur naar je gegevens. Die moet op slot kunnen, en daar hoort een vast lijstje bij.
Al het verkeer loopt versleuteld. Sleutels sla je nooit op in je code zelf, maar in een omgevingsvariabele. Anders staan ze in je back-ups en in je versiebeheer.
Beperk daarnaast de rechten tot het minimum. Heeft de koppeling alleen voorraadgegevens nodig? Geef dan geen toegang tot klantgegevens. Veel leveranciers bieden daar aparte sleutels voor.
Stel ook een limiet in op het aantal verzoeken. Dat beschermt tegen misbruik en tegen een fout in je eigen code.
Let tot slot op wat je zelf openzet. Ook WordPress heeft zulke adressen ingebouwd, en die staan soms opener dan bedoeld. Dat controleer ik standaard bij onderhoud.
Gaat het om persoonsgegevens of betalingen, dan hoort er ook een verwerkersovereenkomst bij. Dat is geen techniek, maar wel verplicht. Leg vast wie daarvoor tekent, want dat vraagt niemand tot het te laat is.
Waarom reageert mijn endpoint traag?
Vaak ligt het niet aan het endpoint, maar aan hoe je het gebruikt. Dit is de meest gemaakte fout bij koppelingen.
Haal je bij elk bezoek live gegevens op, dan wacht je pagina op een server die jij niet beheert. Is die traag, dan is jouw site traag. Ligt hij eruit, dan hangt jouw pagina.
Ik zet daarom bijna altijd een tussenlaag ertussen. De gegevens worden periodiek opgehaald en lokaal bewaard. Je bezoeker krijgt de opgeslagen versie te zien, en dat gaat razendsnel.
Hoe vaak je ververst hangt af van je situatie. Voorraadstanden per kwartier, openingstijden een keer per dag. Alleen bij een boeking of betaling wil je echt live gegevens.
Stel in dat geval een maximale wachttijd in van een paar seconden. Meer daarover lees je bij cache.
Meet een keer hoe lang zo’n verzoek duurt. Zit je boven de seconde, dan hoort het sowieso niet in de route die je bezoeker moet afwachten.
Loop je vast op een koppeling of weet je niet of een dienst wel te koppelen is? Beschrijf je situatie via het formulier hieronder. Ik kijk naar de documentatie van die partij en zeg je of het kan en wat het ongeveer kost. Blijkt het niet rendabel, dan hoor je dat ook. Vermeld je plaats, dan weet ik meteen waar je zit.
