Een van de projecten waar ik aan heb gewerkt was om een API voor ons e-mail platform te ontwikkelen, waarmee klanten analytische data van hun mailings op kunnen halen.

Binnen ons e-mail platform was het altijd al mogelijk om zeer gedetailleerde informatie in te zien rondom verzonden mailings/e-mailcampagnes. Hierbij is onder andere in te zien hoeveel mensen de e-mail hebben ontvangen en geopend, op welke links zijn geklikt, vanaf welke apparaten, etc. We kregen echter regelmatig de vraag of deze informatie ook op een of andere manier uitgewisseld kon worden met andere systemen. De mogelijkheid bestond hiervoor echter nog niet, maar vanwege de grote vraag is er besloten om een web API te ontwikkelen waarmee klanten een koppeling kunnen maken. Op die manier kunnen ze hun eigen systemen weer voeden met de resultaten van een verstuurde mailing.

Ontwikkeling

Hoewel de features van de API niet door mijzelf zijn bepaald kwam de ontwikkeling wel volledig bij mij terecht. Daar was ik blij mee want het was een erg leuke en leerzame opdracht. De API zou met .NET Core 3.1 ontwikkeld worden zodat deze op een Ubuntu server gedraaid kon worden. Zelf had ik op dat moment nog maar weinig ervaring met .NET Core en Ubuntu, behalve dat ik hier zelf wel al mee aan het hobbyen was in mijn eigen tijd. Maar nu kreeg ik de mogelijkheid om deze beperkte kennis uit te breiden en voor een echt product in te zetten. Ik kreeg dan ook de vrijheid om veel research te doen, wat erg meehielp.

Met de ontwikkeling van de API hebben we ook besloten om niet langer de documentatie zelf te schrijven, maar deze te laten genereren d.m.v. de Swagger OpenAPI standaard. Dit betekent dat er ook rekening gehouden moet worden met het juist opzetten van de code om de documentatie op de juiste wijze te laten genereren. Doordat er van een open standaard gebruik wordt gemaakt is het voor een klant ook makkelijk automatische code in de gewenste programmeertaal te laten genereren. Voor ons is het weer makkelijk om de documentatie met weinig moeite beschikbaar te stellen en er komt vrijwel geen onderhoud bij kijken doordat alles gegenereerd wordt.

Om de API te kunnen hosten zijn er een drietal nieuwe virtuele servers neergezet die op Ubuntu draaien: een development/test server en twee productie servers. Deze zijn niet via het internet benaderbaar, maar alleen via het interne netwerk. Voor de servers staat namelijk een API manager die verantwoordelijk is voor de authenticatie. Hiervoor gebruiken we Kong. Vervolgens staat voor de API manager weer een loadbalancer, waar we haproxy voor gebruiken.

Functionaliteiten

De eerste versie van de API zou nog niet alle functionaliteiten bevatten. Alleen de methoden die op het huidige moment voor een klant noodzakelijk waren zijn geïmplementeerd. Vervolgens zou de API regelmatig uitgebreid worden met nieuwe methoden.

De eerste versie bevatte de volgende methoden.

Mailing overzicht op basis van criteria

Met deze methode kun je een reeks aan criteria meegeven waar de mailings aan moeten voldoen die je op wilt zoeken. Denk hierbij aan een naam van het e-mailbericht of abonnement, of bijvoorbeeld de periode waarin de verzending heeft plaatsgevonden.

Het resultaat is een gepagineerde lijst met mailings die aan de criteria voldoen. Daarbij bevat iedere mailing een unieke ID die gebruikt kan worden om gedetailleerdere informatie voor die specifieke mailing op te zoeken.

Algemene details voor specifieke mailing ophalen

Door deze methode aan te roepen met de ID van een specifieke mailing kun je daarvoor gedetailleerdere informatie ophalen. Deze informatie bevat onder andere naar hoeveel mensen de mailing is verzonden, hoeveel mensen deze hebben ontvangen of geopend en ook hoeveel mensen hebben doorgeklikt op links binnen de e-mail.

Link en klik details voor specifieke mailing ophalen

Met deze methode kun je weer iets verder inzoomen op een specifieke mailing, in dit geval op de links van het verstuurde e-mailbericht. Je krijgt een gepagineerde lijst terug met links die in de e-mail zijn gebruikt. Voor iedere link wordt onder andere omschreven wat de URL is, wat voor type link het is (bijvoorbeeld een externe link of een uitschrijflink), hoeveel mensen er minstens één keer op hebben geklikt en hoeveel kliks er in totaal zijn.

Tag en score details voor specifieke mailing ophalen

Met deze methode kun je inzoomen op de tags die in een specifieke mailing zijn gebruikt. Tags zijn sleutelwoorden die aan een e-mailbericht, actie of link gekoppeld kunnen worden. Wanneer je dan het e-mailbericht opent of een link daarin aanklikt, dan wordt de score opgehoogd voor de tag die daaraan gekoppeld staat. Tags kunnen gebruikt worden voor opvolgende mailings. Ook met deze API methode krijg je een gepagineerd resultaat terug, met daarin de tags en bijbehorende scores.

Ping methode

Deze methode vereist weinig uitleg. Dit is een methode om de beschikbaarheid van de API te controleren. Draait de API? Dan krijg je "Pong" terug als reactie.