Teamleader Blog Article

Teamleader API: waarom kozen we een RPC-architectuur?

Teamleader API: waarom kozen we een RPC-architectuur?

“Waarom kozen jullie niet voor een REST-architectuur om jullie nieuwe API te schrijven? Dat is toch de standaard tegenwoordig?” Het moet zowat de vaakst terugkerende opmerking zijn in de eerste feedback die we krijgen op onze nieuwe API. Een compleet terechte opmerking waar we graag wat dieper op ingaan.

“We wilden dat de API vooral logisch overkomt vanuit menselijk standpunt en niet noodzakelijk vanuit technisch standpunt.”

Bij het ontwerpen van de nieuwe API hanteerden we een aantal basisprincipes: de software moest voldoende schaalbaar (en op die manier ook futureproof) zijn, en ook de onderliggende logica vonden we heel belangrijk. We wilden dat de API vooral logisch overkomt vanuit menselijk standpunt en niet noodzakelijk vanuit technisch standpunt. Als je iets met de API wilt doen, moet dat gebeuren op een manier die intuïtief klopt, net alsof je in het “echte” leven iets zou doen.

No REST for the wicked20171212_API_Inline1_producttoplatform.jpg

Dat verklaart ook waarom we niet voor REST hebben gekozen als architectuur. Op zich is er niets mis met REST, natuurlijk, en voor sommige doeleinden is het ongetwijfeld de juiste keuze. Ondanks de vele varianten is het een soort standaard geworden voor dit soort projecten. Met andere woorden: we hadden het onszelf gemakkelijk gemaakt door voor REST te kiezen. Maar dat hebben we bewust niet gedaan.

"Door het onszelf iets moeilijker te maken, maken we het de eindgebruiker een stuk eenvoudiger."

Door het onszelf iets moeilijker te maken en geen REST-architectuur toe te passen, maken we het de eindgebruiker een stuk eenvoudiger. REST verplicht je namelijk om een specifieke terminologie te gebruiken die vaak behoorlijk afwijkt van wat je gewoon bent, en dwingt je in een bepaald keurslijf. Bovendien is het in dit type architectuur niet zo eenvoudig om de veranderende status van een object weer te geven. En in software als Teamleader, waarin alles rond flows of processen draait, heb je nu eenmaal voortdurend statusveranderingen. Denk bijvoorbeeld aan een factuur, die geboekt, betaald of gecrediteerd kan zijn.

20171212_API_Inline2_RPC.jpgREST kent haar beperkingen

Daarnaast is een REST-API in principe zeer omslachtig, waardoor veel bedrijven toch liever wat van de standaard afwijken. Het is niet altijd duidelijk wat achter de schermen zal gebeuren als je bepaalde zaken aanpast. Zo introduceert een REST-API vaak bijkomende eigenschappen die niet overeenkomen met de realiteit van je software (zoals de status van een factuur in Teamleader aanpassen). De bijkomende effecten van zo’n aanpassing (of de eigenschappen die daarmee verbonden zijn), zijn niet vanzelfsprekend.

Bij onze actiegerichte API laten we deze velden achterwege, en bouwden we uitzonderlijke API endpoints om die acties uit te voeren. Zo weet je steeds dat je een actie uitvoert waarbij bijkomende verplichte waarden nodig zijn. Denk maar aan het factuurnummer bij het boeken van een factuur, het bedrag bij het registreren van een betaling, of de datum bij het inplannen van een taak.

De keuze voor RPC

20171212_API_Inline3_accessible.jpgOut REST, in RPC dus. Waarom precies? REST werkt heel goed voor CRUD-operaties (Create, Read, Update en Delete). Maar wanneer je andere acties moet uitvoeren, zoals een factuur boeken of een contact aan een bedrijf linken, kan je al snel veel gebruiksvriendelijker werken met een ander model. Wij deden vooral inspiratie op bij Slack - die een meer actiegerichte RPC-stijl hanteren. Die manier van werken sluit ook beter aan bij Teamleader, omdat we duidelijkheid verkiezen boven technische termen die geïntroduceerd worden om een bepaalde standaard te volgen.

De grote voordelen?

  1. Acties zijn meteen duidelijk, omdat ze niet verborgen zitten in properties zoals bij REST. Je weet meteen welke data je moet meegeven bij welke actie en wat die actie doet met je ‘object’. Duidelijker, voorspelbaarder, en dus ook betrouwbaarder.
  2. Je hebt minder nood aan technische termen om specificaties te volgen. Alle acties in Teamleader vertalen naar REST-endpoints zou een hele klus zijn - en bovendien minder duidelijk te begrijpen.

De grootste kanttekening bij dit verhaal: developers zijn vertrouwd met REST-API’s. We zijn er echter rotsvast van overtuigd dat elke developer snel met deze nieuwe aanpak overweg zal kunnen, zodra je de basisprincipes op developer.teamleader.eu hebt doorgenomen.

Veranderen is niet eenvoudig - maar we zouden geen developers zijn als we blind vasthielden aan principes uit het verleden. Zodra je aan de slag gaat met de nieuwe API, zal je snel merken dat RPC de juiste keuze is.