REST API's maken het mogelijk dat clients, zoals browser-applicaties, kunnen communiceren met een server. Meestal wordt REST ingezet om webservices te bouwen en als gebruiker ben je dan afhankelijk van REST voor het goed functioneren van bijvoorbeeld websites. Wanneer een REST API niet beschikbaar is of traag werkt, dan veroorzaakt dat storingen. Daarom is het belangrijk om een REST API op de juiste manier te ontwikkelen voor een optimale prestatie en gebruiksgemak. In dit blogartikel bespreken we de vijf best practices om een goede REST API te ontwerpen.
Wanneer heb je REST API nodig?
REST API is de standaard voor het ontwikkelen van webservices. Webservices maken het mogelijk dat systemen met elkaar kunnen communiceren via het internet op basis van HTTP-protocol. Front-end applicaties, bijvoorbeeld een single page, roepen een API aan en de backend is dan meestal een REST API. REST API's zorgen er bijvoorbeeld voor dat je online afspraken kunt maken, formulieren kunt invullen of adressen kunt valideren. Het is een architectuurstijl om eenvoudig data uit te wisselen via HTTP voor al je webservices.
Worstel je met een specifiek integratievraagstuk? Of heb je een vraag over bepaalde systemen, applicaties of Integration as a Service?
Vijf best practices voor REST API
Voor de beste prestatie van een REST API en optimaal gebruikersgemak, zijn dit de vijf best practices om een goede REST API te bouwen.
1. Bouw eerst een model van je data
Vaak zien we nog dat er voornamelijk wordt gewerkt met point-to-point REST API's: je hebt een specifieke vraag, waarop een antwoord nodig is en daarvoor wordt een REST API ontwikkeld. Maar dan eindig je met een ingewikkelde soep van verschillende REST API's. Bedenk eerst hoe de data eruit moet zien voor de buitenwereld en start met modelleren. Binnen dat datamodel maak je een indeling van al je collecties met daarin de resources. Pas dan verbind je die met elkaar. Door eerst een model te maken van je data krijg je een logische opbouw van je REST API's.
2. Zorg dat je guaranteed delivery borgt
Onderzoek eerst of de systemen die je aan elkaar wilt koppelen wel geschikt zijn om met duplicates om te gaan en om REST te ontsluiten. Je wilt namelijk geen data kwijtraken of dubbel ontvangen. Fouten handel je af middels HTTP-codes, zodat een API-gebruiker weet wat er fout is gegaan. Je herkent vast wel de volgende HTTP-code ‘404 Not Found’ wanneer je een webpagina (de resource) wilt bezoeken die niet gevonden kan worden. Het is dus belangrijk dat je guaranteed delivery borgt en als dat niet lukt, dat je dan werkt met HTTP-codes. Zo weet je als ontwikkelaar wat er fout gaat en krijgt de gebruiker van de REST-API ook een specifieke foutmelding te zien.
3. Gebruik zoveel mogelijk standaarden
Gebruik voor het maken van links tussen collecties en resources (hypermedia), in de naamgeving van collecties en bij het beschrijven van fouten, zoveel mogelijk standaarden. Zoals bij punt twee al is aangegeven: je weet dan welke fout de oorzaak is van een storing. En als het gaat om de benaming van collecties: gebruik bijvoorbeeld 'Klanten’ voor de collectie met de resources ‘Klant'. Zo voorkom je verwarring en zorg je ervoor dat je REST API goed werkt.
4. Maak onderscheid tussen je afnemers
Een REST API bouw je voor een gebruiker of voor communicatie tussen applicaties. Het is goed om je er bewust van te zijn dat REST dan een iets andere invulling moet krijgen. Een gebruiker haalt bijvoorbeeld data op via een webapplicatie uit de backend. Dan is het gebruik van caching interessant. Een subset van de data komt dan op het systeem (bijvoorbeeld een smartphone) van de gebruiker te staan. Voor communicatie tussen applicaties heeft caching geen zin, want daarvoor wordt de hele dataset gebruikt. Bij caching krijgt de applicatie dus een kopie van die dataset en dan wordt de cache te groot.
5. Zorg dat er nooit een actie in een URL komt te staan
Wanneer je namelijk een actie in een URL plaatst, dan is het geen REST meer. Bovendien zit in het HTTP-verzoek al het doel van de actie verwerkt, zoals GET om een resource op te halen, POST om een resource aan te maken, PUT om een resource te updaten en DELETE om een resource te verwijderen. Dus houd je aan de REST-standaarden en gebruik HTTP Verbs om acties uit te voeren.
Meer weten over REST?
Bekijk dan onze video over hoe je een goede REST API definieert. Heb je hulp nodig bij REST API? Op dit moment zijn onze experts hard aan het werk, maar laat gerust je vraag achter of plan een moment in om te chatten.
