API days 2019

We hebben al een hele weg afgelegd op vlak van technologie en computers en dit zette de eerste talk van deze tweedaagse conferentie heel mooi in de verf.

• De eerste evolutie in de geschiedenis van IT was de mens die met computer leert communiceren, door middel van programmeertalen, computermuizen en GUIs.  
• De tweede evolutie, computers die met andere computers leerden communiceren dankzij ARPANET (de voorloper van het internet).
• Nu zitten we middenin de derde grote evolutie, namelijk software die met andere software leert praten en dit door middel van API's. 

Wanneer we vandaag informatie opzoeken, zal de meerderheid van de mensen ‘even Googlen’ of Wikipedia raadplegen. En volgens deze laatste luidt de officiële definitie van een ‘API’ als volgt: “Een application programming interface (API) is een verzameling definities op basis waarvan een computerprogramma kan communiceren met een ander programma of onderdeel.” Wij leggen het begrip API uit aan de hand van een concreet voorbeeld.

Vrij vertaald kan je een API vergelijken met een soort boodschapper, één die een vraag (de zogenaamde ‘request’) komt halen en later terugkomt met het gepaste antwoord (‘response’). 

Zomer. Je zit op een terras, dorstig. De kelner merkt dit op en komt vervolgens aan jou vragen wat je wenst te drinken (request), later komt hij terug met je drankje (response). Gezien wij zelf niet de keuken kunnen ingaan, de koelkast opentrekken en alles rustig opdrinken is er een tussenpersoon nodig die voor de nodige communicatie zorgt: de kelner. Of om on-topic te blijven: de API.

En dat is wat een API doet; deze zorgt voor de communicatie tussen verschillende kanalen zonder dat de gebruiker iets merkt van de daaraan gebonden complexiteit. Vertalen van een vraag naar een antwoord, ongeacht het pad (of paden!) die daarvoor moeten bewandeld worden.

Het communiceren van software naar software gebeurt dus al jaren via API’s. Doorheen de jaren zagen we echter wel al meerdere vormen van API’s de revue passeren, zoals SOAP, REST en nu ook GraphQL.

GraphQL kent zijn ontstaan in 2015 bij Facebook. Het bedrijf zocht een manier om de hoeveelheid data die bij elke API request verstuurd werd, in te perken. 
Vroeger was het namelijk zo dat sommige API's te weinig data verstuurden, waardoor meerdere requests naar meerdere API's nodig waren. Het kwam ook voor dat een API net veel te veel data doorstuurde, terwijl we eigenlijk maar geïnteresseerd waren in een klein stukje hiervan. Niet zo efficiënt dus.
GraphQL lost deze problemen op door de afnemer van de API zelf te laten kiezen welke data ze willen terugkrijgen en doet dat met een syntax die leesbaar is door API-leken.

Het gebruik van de GraphQL technologie is nog niet wijd verspreid, maar kent een stevige opmars. Drupal heeft alvast een GraphQL module met support voor de volledige officiële GraphQL specificaties.

Een heleboel talks onderstreepten tevens ook het belang van goede documentatie. API’s zijn in essentie eigenlijk niet software die met andere software communiceert, maar mensen die met andere mensen praten. De aanbieder van een API moet duidelijk vertellen wat hun API allemaal aanbiedt, zodat andere mensen die correct kunnen gaan gebruiken. 
In sommige talks durfden ze zelf stellen dat de documentatie even belangrijk is als de code, omdat code waarvan niemand weet hoe ze gebruikt wordt, eigenlijk nutteloos is. 

Uit deze talks staken we dus heel wat nuttige & praktische tips op:

• Laat iemand zonder kennis van de technologie of domain kennis de documentatie nalezen. Als die het te verwarrend vindt, dan moet de documentatie duidelijker geschreven worden.
• Schrijf documentatie in markdown. Dit is een syntax die ook niet-technische mensen zeer makkelijk kunnen lezen.
• READMEs zijn geen complete docs, maar een intro. Gebruik ze meer als installatiestappen.
• Documentatie is communicatie: schrijf geen dingen die je niet in persoon tegen iemand zou zeggen (zoals neerbuigende opmerkingen als "iedereen weet dit").
• Voer net zoals code reviews ook documentation reviews in. 

Een van de talks had ook een interessante waarschuwing, namelijk dat als een API zich op een bepaalde manier gedraagt, mensen die ook zo zullen gebruiken, ook al is deze manier van gebruiken niet gedocumenteerd.
Bijvoorbeeld, een API maakt geen belofte qua volgorde waarop data binnen komt, maar de ontvanger van de API kan proefmatig wel ondervinden dat de volgorde een zekere logica volgt. Die logica breken moet met evenveel voorzichtigheid behandeld moeten worden, als veranderingen aan gedocumenteerd gedrag.

Een andere key takeaway van de conferentie was hoe belangrijk het is om je API te decouplen (loskoppelen) van de implementatie ervan. Ditzelfde concept dat software makkelijker herbruikbaar maakt, maakt dus ook API’s meer herbruikbaar. Een heleboel sprekers raadde daarom aan om eerst de API op te zetten, nog voordat de eerste applicatie die hem kan gebruiken, wordt geschreven. Dit heeft namelijk als voordeel dat je de code van de API achterliggend makkelijker kan aanpassen, zonder de implementaties die van de API gebruik maken, kapot te maken.

Een leuke talk door David O’Neill onderstreepte het belang om absoluut alle calls met API’s te loggen. Door de complexe natuur van het beestje verzamel je best zoveel mogelijk informatie, ook wanneer alles goed loopt. Hij vestigde hierbij ook aandacht op GDPR, want uiteraard moet ook logging van API calls voldoen aan de GDPR richtlijnen.

De centrale thema's van de conferentie dit jaar waren de kracht van GraphQL, het belang van goede documentatie en het concept om net als alle andere software ook API’s van hun implementatie los te koppelen.

API’s zullen in de toekomst steeds belangrijker worden, en door deze best practices kunnen we ook deze evolutie in goede banen leiden.