Hoe herken je een goede API?

Klanten vragen ons met enige regelmaat of wij hun website of webapplicatie kunnen koppelen met een extern systeem of platform. Hierdoor zorgen zij ervoor zorgen dat alles vanuit een systeem beheerd wordt in plaats van dat zij continu moeten wisselen tussen diverse systemen. Dit neemt logischerwijs heel wat werk uit handen.

Een voorbeeld van een dergelijke koppeling is het direct kunnen versturen van orders uit een webshop naar een verwerkingssysteem en het ophalen van producten uit een zogenaamd voorraadsysteem. Ook het ophalen van vacatures en het versturen van sollicitaties naar een ATS of het sync houden van accounts in een website met een CRM-systeem zijn voorbeelden van een slimme koppeling van systemen. Maar hoe doe je dat? Waar moet je op letten? Back-ender Martijn neemt je mee.

Hoe herken je een goede API

Voor een koppeling maken we gebruik van zogenaamde API’s van het te koppelen platform. API staat voor Application Programming Interface. Dit is eigenlijk een interface die de data uit het platform gestructureerd en leesbaar voor een ander systeem teruggeeft. Bij Elephant zeggen we altijd: als er een API is kunnen we het koppelen. Er is alleen wel een heel belangrijke sidenote: hoeveel tijd dit kost en hoe betrouwbaar we deze koppeling kunnen maken is namelijk afhankelijk van de API. Ik ga je daarom in deze blog laten zien van welke API’s we bij Elephant blij worden en met welk type API’s we liever niet werken.

Documentatie & Support

Het allerbelangrijkste wanneer wij met een API gaan koppelen is de beschikbaarheid van goede documentatie en de beschikbaarheid van support wanneer de documentatie tekortschiet. Een goede API documentatie moet in ieder geval de volgende onderdelen bevatten:

• Inzicht in alle beschikbare methodes (endpoints) met bijbehorende parameters van de API
• Documentatie over authenticatie
• Code voorbeelden in verschillende talen

Enkele voorbeelden van goede documentatie:

• https://mailchimp.com/developer/
• https://developers.pipedrive.com/
• https://developer.twitter.com/#/
• https://help.getharvest.com/api-v2/

API Type/Structuur

Je kunt een structuur eigenlijk zien als afspraken over hoe de API in de basis werkt. Door deze zogenaamde afspraken weten wij als developers precies waar we aan toe zijn en kunnen wij goed inschatten hoe een bepaald systeem werkt. In API-land zijn verschillende type API structuren bekend. Veruit de meest bekende is hierin REST. Dit staat voor REpresentational State Transfer. Daarnaast zien we ook zogenaamde SOAP API’s. Tot slot komen we ook nog (veel te vaak) API’s tegen die zich eigenlijk aan geen enkele structuur houden. Wij werken zelf het liefste met goed gedocumenteerde REST API’s omdat we hier het snelste mee kunnen implementeren. Ook kunnen we met dit type API een betrouwbare koppeling neerzetten doordat we een goede verwachting hebben van de werking van de API.

Packages & plugins

Veel grote partijen als bijvoorbeeld Mailchimp en Google hebben vaak ook packages en plugins beschikbaar om de implementatie nog makkelijker te maken. Bij een goede plugin kan dat zelfs betekenen dat er geen ontwikkeltijd van onze kant nodig is. Een plugin heeft wel nadelen. Wanneer je namelijk ook maar iets anders wil in de werking van de plugin, is deze direct niet meer bruikbaar voor de usecase. In dat geval moet je direct naar een stukje maatwerk. Dit zien wij in negen van tien gevallen gebeuren. Wanneer je al met API’s bezig bent om je eigen specifieke bedrijfsproces te optimaliseren, kom je hier vaak op uit. Bij een plugin is de werking zo vastgelegd dat deze geen rekening kan houden met ieder mogelijk bedrijfsproces.

Een hele mooie tussenoplossing die wel tijd kan besparen maar geen beslissingen maakt over de werking zijn zogenaamde packages. Dit is eigenlijk een tussenlaag (wrapper) tussen de API en de code die wij schrijven. Deze tussenlaag maakt het makkelijker om API’s aan te spreken. Grote platformen hebben deze meestal voor iedereen beschikbaar en het gebeurt ook regelmatig dat andere developers een package ontwikkeld hebben voor hun eigen project en dit open source hebben gemaakt. Het is hierbij wel belangrijk om te checken wie deze package ontwikkeld heeft en of deze package onderhouden wordt. Waar je deze packages kunt vinden verschilt per taal. Voor PHP wordt hiervoor bijvoorbeeld Packagist gebruikt.

Onderstaande package wordt onderhouden door andere developers in plaats van Mailchimp zelf. Op basis van het aantal downloads, updates en openstaande issues kun je zelf wel inschatten of deze actief wordt onderhouden en of je deze dus goed kunt gebruiken: https://packagist.org/packages/drewm/mailchimp-api