Er bestaat geen handleiding waarin staat: zó definieer je een REST API. Gelukkig hebben we al zo vaak REST ontwikkeld, dat we ondertussen alle ins-en-outs wel kennen. En die kennis willen we je niet onthouden, daarom geven we je in dit blogartikel vijf tips om een goede REST API te definiëren.
1. Bouw een robuuste REST API
Met robuust bedoelen we dat een API niet omvalt, hapert of trager wordt wanneer er bijvoorbeeld ineens meer verkeer is naar je website. Een API moet snel en goed blijven werken en schaalbaar zijn. Bij het bouwen van je REST API denk je dus na over wat er met je data gebeurt en hoeveel data je deelt. Tegenwoordig verwachten we allemaal dat een webpagina binnen enkele seconden laadt. Caching helpt hierbij. Aan de hand van een unieke identifier ziet de API of de data die je hebt nog recent is of dat er een update moet plaatsvinden. Wanneer er dus meer verkeer is of een grote hoeveelheid data wordt gedeeld, zorgt een schaalbare en robuuste REST API dat de data-uitwisseling geen moeite kost.
2. Denk na over de structuur van je data
Een API moet logisch zijn opgebouwd. Dat betekent dat je moet nadenken hoe je je data structureert, want de structuur van je data bepaalt hoe je je API vormgeeft, zodat je de juiste informatie terugkrijgt. Welke collecties aan informatie heb je allemaal en hoe ga je je REST API onderverdelen? Een collectie bestaat bijvoorbeeld uit klanten en een subcollectie van een klant bevat adresgegevens, een profielfoto en een telefoonnummer. HTTP-methoden als GET, PUT, POST en DELETE zijn hierbij ook van belang om de juiste actie uit te voeren.
Wat als een actie misgaat? Ook fouten geef je een bepaalde structuur mee. Ten eerste om te zien dat er iets misgaat en ten tweede om te ontdekken wat er precies niet naar behoren werkt. Iedereen kent wel de 404-pagina: de foutmelding die je terugkrijgt wanneer je een webpagina wilt bezoeken die niet meer bestaat. Een foutcode is niet alleen handig voor de eindgebruiker, maar ook voor de beheerder. Je krijgt namelijk inzicht in waar en waarom een verzoek misgaat.
Structuur zorgt ook voor een snelle REST API en applicatie. JSON geeft structuur aan je data. Stel, een eindgebruiker vraagt een klantenbestand op wat bestaat uit 3000 klanten. Dan wil je hem of haar niet ineens die gigantische hoeveelheid aan informatie geven, maar juist gedoseerd. Terwijl je door die gegevens scrolt, wordt geleidelijk meer data toegevoegd (dynamic content). Een passende structuur van je data zorgt er dus voor dat je de juiste data snel terugkrijgt en als er iets misgaat, je direct weet wat en waarom iets niet lukte.
Worstel je met een specifiek integratievraagstuk? Of heb je een vraag over bepaalde systemen, applicaties of Integration as a Service?
3. Ontwikkel een veilige REST API
Beveiliging bevindt zich op meerdere plekken, bijvoorbeeld voor en achter een inlog. Must-haves op het gebied van veiligheid zijn dan ook encryptie en OpenID Connect. Encryptie versleutelt data, zodat het niet door iedereen kan worden gelezen. Dat doe je vanuit de client. Welke gegevens een gebruiker mag inzien, regel je door rollen en rechten in te bouwen, dus door autorisatie toe te passen.
OpenID zorgt ervoor dat je kunt inloggen via een andere ‘organisatie', bijvoorbeeld met je Google-, Apple- of Facebookaccount. Je wilt namelijk dat gebruikers snel aan de slag kunnen en het kan een drempel zijn om voor jouw dienst weer een account aan te maken. Met OpenID bied je de eindgebruiker gemak, maar ook een veilige manier om gegevens op te vragen met authenticatie.
4. Zorg voor goede documentatie
Door goed te documenteren, ben je voorbereid op de toekomst. Je helpt hiermee andere ontwikkelaars, maar het maakt ook je API gereed om nieuwe applicaties op aan te sluiten. Dus zodra je aan de slag gaat met een REST API, is het handig om na te denken over wat je wilt bereiken met de data die je deelt, wie welke informatie mag inzien en hoe je de data deelt. OpenAPI Specification is een standaard voor REST API documentatie. Die specificaties kun je zelfs visueel weergeven, zodat je je API eenvoudig en geautomatiseerd kunt testen. Door goed te documenteren, middels OpenAPI Specification, gaat je API langer mee!
5. Maak je API future-proof
Vroeger definieerde je je API en dat was dat. Tegenwoordig blijven we sleutelen aan onze API's. Dat heeft wel gevolgen voor de manier waarop je je REST API bouwt, zodat deze blijft werken voor je afnemers. Stel, je werkt met verschillende versies. De eerste versie roept klantdata aan in het Engels, maar de tweede versie in het Nederlands. Het is dan van belang dat je API stateless is, zodat er twee versies van de REST API naast elkaar kunnen draaien en je afnemer hier geen last van heeft.
Hypermedia as the Engine of Application State (HATEOAS) geeft aan welke versies er allemaal bestaan. Standaard wordt dan de laatste versie gebruikt. De API ziet welke collecties er zijn en kan dan een collectie aan een andere refereren. Via een link (hypermedia) haalt de API dan daar de juiste data op. Op die manier kun je sleutelen aan een API en valt de koppeling niet direct om wanneer er iets verandert.
Stel gerust je vraag over REST API
Deze tips nog een keer terugzien? We maakten er een video over! Heb je verder nog vragen over REST API? Laat dan hier je vraag achter of plan een moment om met een van onze API-specialisten te chatten.
