APIs ontwerpen als een pro: essentiële strategieën voor het bouwen van high-performance API's

Dit artikel is een gewaardeerde bijdrage uit onze community en is door DataCamp geredigeerd voor duidelijkheid en nauwkeurigheid.

Wil je je eigen expertise delen? We horen graag van je! Dien je artikelen of ideeën in via ons Community Contribution Form.

De kaarten die je ziet in taxi- en bezorgapps zijn te danken aan de Google Maps API, die ontwikkelaars gebruiken om deze functionaliteit mogelijk te maken. Google Maps API is de standaard-API die websites en apps gebruiken om realtime kaarten te tonen. Wil je het precieze aantal weten? Er zijn momenteel 5.567.291 live websites die de API gebruiken.

Waarom is de Google Maps API zo succesvol? Ja, deels omdat hij van Google zelf is, maar ook vanwege het API-design, waardoor ontwikkelaars hem makkelijk in hun producten kunnen integreren.

Google Maps API is slechts één voorbeeld; er zijn talloze populaire API's op de markt, zoals PayPal, Stripe, enzovoort. Een deel van het succes van deze bedrijven is zelfs toe te schrijven aan hun API's.

Elke website of applicatie kan zijn kernfunctionaliteit nu toegankelijk maken via API's. Uiteindelijk hangt de adoptie van een API echter af van hoe goed die is ontworpen. In deze blog verkennen we de basis van API-design en de best practices die je moet volgen om ervoor te zorgen dat ontwikkelaars dol zijn op je API.

Wat is API-design?

API-design is het proces van het definiëren van methoden en dataformaten die applicaties kunnen gebruiken om informatie op te vragen en uit te wisselen. Het omvat het specificeren van de endpoints of URL's die ontwikkelaars kunnen gebruiken, de dataformaten die ze moeten verzenden en ontvangen, en het verwachte gedrag van de API.

Hoewel dit de technische aspecten van een API zijn, wordt API-design bepaald door het doel van een API; het waarom erachter. Inzicht in het doel van een API strijkt de plooien in het ontwikkelproces glad, omdat het duidelijkheid geeft over verwacht gedrag, beperkingen en mogelijke toekomstige ontwikkelingen. API-design valt nu onder de bredere paraplu van API-beheer om consistentie te waarborgen tussen het geplande ontwerp en de geïmplementeerde API.

Wil je je skills in API-integratie en -beheer ontwikkelen? Bekijk dan DataCamp's cursus Werken met de OpenAI API, die je helpt AI-gestuurde applicaties te bouwen.

Hoe ontwerp je een API

Elke API is anders, afhankelijk van het doel en de functionaliteit. Toch zijn er een aantal universele leidende principes die elke ontwikkelaar zou moeten volgen om een robuuste en ontwikkelaarsvriendelijke API te bouwen. Zo pak je het aan:

Stap 1: Begrijp het doel van je API

Voordat je de blauwdruk van je API uittekent, moet je zorgen dat alle stakeholders helder hebben wat de API gaat doen. Werk nauw samen met businessleiders om de algemene doelstellingen en doelen te verduidelijken. Begrijp hoe de API in het grotere geheel past. Communiceer indien mogelijk rechtstreeks met de eindgebruikers of ontwikkelaars die met de API gaan werken. Verzamel feedback over hun behoeften, pijnpunten en verwachtingen om inzicht te krijgen in de praktische use-cases van de API.

Het doel van de API bepaalt de functionaliteit, features, hoe die wordt gedocumenteerd, welke beveiligingsimplementaties nodig zijn en welke API-specificatie je kiest.

Kies de juiste API-specificatie

Er zijn verschillende API-specificaties, elk geschikt voor een bepaald use-case. Dit zijn enkele van de populairste:

OpenAPI (Swagger)

OpenAPI is een breed gebruikte standaard voor het beschrijven van RESTful API's. Het staat bekend om zijn eenvoud, maakt het genereren van documentatie gemakkelijk en biedt een gestandaardiseerde manier voor ontwikkelaars om de API te begrijpen en ermee te werken. OpenAPI gebruikt een JSON- of YAML-indeling om de endpoints, request- en responseformaten en authenticatiemethoden van de API te specificeren. Het is geschikt voor stateloze communicatie via HTTP en een goede keuze voor API's die bedoeld zijn voor een breed publiek.

GraphQL-schema

GraphQL is een alternatief voor RESTful API's en de specificaties ervan worden vaak gedefinieerd met een schemataal. Een GraphQL-schema beschrijft de types specifieke data die kunnen worden opgevraagd en de structuur van die queries. Het is geschikt voor scenario's waarin clients precieze controle nodig hebben over de data die ze willen ophalen.

Breid je kennis uit over het bouwen van machinelearningmodellen als API's met Flask. Bekijk DataCamp's uitgebreide tutorial Machine Learning Models API in Python.

RAML (RESTful API Modeling Language)

RAML is een op YAML gebaseerde taal voor het beschrijven van RESTful API's. Het biedt een voor mensen leesbare manier om de structuur, endpoints en datatypen van de API te definiëren. Gebruik het wanneer leesbaarheid en eenvoud prioriteit hebben.

SOAP (Simple Object Access Protocol)

SOAP is een protocol voor het uitwisselen van gestructureerde informatie in webservices. Het wordt vaak gebruikt in enterprise-omgevingen waar gestandaardiseerde communicatie nodig is. Het is de beste keuze wanneer je met legacy-omgevingen te maken hebt.

WSDL (Web Services Description Language)

WSDL wordt vaak gebruikt voor het beschrijven van SOAP (Simple Object Access Protocol) webservices. Het definieert de operaties, berichten en datatypen voor webservices, waardoor gestandaardiseerde communicatie tussen verschillende systemen mogelijk wordt. Het is het meest geschikt voor enterprise-applicaties waar strikte contracten en gestandaardiseerde communicatie vereist zijn.

AsyncAPI

Vergelijkbaar met OpenAPI maar specifiek ontworpen voor asynchrone API's, richt AsyncAPI zich op message-driven architecturen en beschrijft het hoe berichten tussen verschillende componenten worden uitgewisseld. Het wordt gebruikt wanneer er geen realtime respons van een API nodig is.

Duik dieper in API-ontwikkeling met DataCamp's tutorial Introduction to FastAPI. Leer hoe je robuuste API's bouwt met moderne frameworks.

Stap 2: Definieer endpoints en resources

De volgende stap is het definiëren van de endpoints en resources. Endpoints definiëren de specifieke URL's (Uniform Resource Locators) of URI's (Uniform Resource Identifiers) die ontwikkelaars kunnen gebruiken om met de API te communiceren. Elk endpoint komt doorgaans overeen met een specifieke bewerking of actie. Gangbare HTTP-methoden zoals GET, POST, PUT en DELETE worden gebruikt om bewerkingen op deze endpoints uit te voeren. Hier is een voorbeeld:

• GET /users: Haal een lijst met gebruikers op.
• GET /users/{id}: Haal details op van een specifieke gebruiker met behulp van de user ID.
• POST /users: Maak een nieuwe gebruiker aan.
• PUT /users/{id}: Werk de details van een specifieke gebruiker bij.
• DELETE /users/{id}: Verwijder een specifieke gebruiker.

Resources vertegenwoordigen de entiteiten of objecten die je API beheert. Dit kunnen van alles zijn: van gebruikers en producten tot reacties of andere relevante entiteiten in je systeem. Elke resource heeft doorgaans een unieke identifier en is gekoppeld aan één of meer endpoints. Bijvoorbeeld:

Resource: users

Attributen: ID, gebruikersnaam, e-mailadres, enz.

Endpoints:

/users (GET - alle gebruikers weergeven, POST - een nieuwe gebruiker aanmaken),

/users/{id} (GET - gebruikersdetails ophalen, PUT - gebruikersdetails bijwerken, DELETE - een gebruiker verwijderen)

Resource: products

Attributen: ID, naam, beschrijving, prijs, enz.

Endpoints:

/products (GET - alle producten weergeven, POST - een nieuw product aanmaken),

/products/{id} (GET - productdetails ophalen, PUT - productdetails bijwerken, DELETE - een product verwijderen)

Stap 3: Bepaal naamgevingsconventies

Wil je dat ontwikkelaars je API waarderen, zorg dan voor duidelijke en consistente naamgevingsconventies. Wees niet te creatief bij het kiezen van namen voor endpoints, resources en parameters; geef prioriteit aan duidelijkheid en eenvoud. Hier zijn enkele richtlijnen:

1. Gebruik zelfstandige naamwoorden voor resources:
• Kies duidelijke en beschrijvende zelfstandige naamwoorden voor je resources. Bijvoorbeeld /users, /products, /orders.
• Vermijd dubbelzinnige of generieke termen. Wees specifiek om het doel van de resource over te brengen.
2. Gebruik werkwoorden voor acties:
• Gebruik HTTP-methoden (GET, POST, PUT, DELETE) om acties op resources weer te geven.
• Houd de werkwoorden consistent over endpoints heen. Gebruik bijvoorbeeld GET om gebruikers op te halen en POST om een nieuwe gebruiker te maken.
3. Wees consistent met meervoudsvormen:
• Bepaal of je resourcenamen enkelvoud of meervoud zijn en wees consistent in je hele API. Kies bijvoorbeeld óf /user óf /users.

Stap 3: Optimaliseer request- en responsepayloads

Een ander cruciaal aspect van het ontwerp van een API-contract is het specificeren van de request- en responsepayloads, oftewel de data die in de request wordt verzonden en de data die in de response wordt verwacht. Het eerste wat je moet doen, is een standaard dataformaat voor je API kiezen, zoals JSON of XML. Beter is om voor JSON te kiezen, omdat dit veel wordt gebruikt dankzij de eenvoud en leesbaarheid. Je kunt leren hoe je JSON gebruikt in DataCamp's cursus Streamlined Data Ingestion with pandas.

Houd je payloads licht, want ze hebben direct invloed op de efficiëntie van je API. Dit kun je doen:

1. Probeer payloadcompressie te implementeren (bijv. gzip) om de grootte van requests tijdens verzending te verkleinen.

2. Ondersteun, indien van toepassing, batch-requests waarbij meerdere operaties in één request worden gegroepeerd.

3. Gebruik query- of headerparameters om je API-endpoints zo te ontwerpen dat ze alleen de data teruggeven die clients nodig hebben.

Stap 4: Implementeer authenticatie en autorisatie

Zorg ervoor dat je in je API-design rekening houdt met beveiliging. Je kunt dat op twee manieren aanpakken: authenticatie en autorisatie.

Voor authenticatie kun je OAuth en API-sleutels implementeren. Een API-sleutel is een eenvoudige en veelgebruikte methode, waarbij een unieke sleutel in de requestheader wordt opgenomen. Deze vorm van authenticatie is echter niet veilig genoeg.

OAuth daarentegen is een robuuster en flexibeler framework, geschikt voor scenario's waarin derde partijen toegang nodig hebben. Definieer voor autorisatie duidelijk de toegangsniveaus en scopes die gebruikers of applicaties kunnen hebben.

Stap 5: Pas API-versiebeheer toe

Gebruikersvereisten en technologie veranderen vaak in de loop van de tijd, waardoor een API moet evolueren. Met versiebeheer kun je wijzigingen aanbrengen in een API zonder het bestaande systeem te breken. Er zijn verschillende vormen van API-versiebeheer die je kunt implementeren, zoals URL-versiebeheer, queryparameterversies, headerversies, enzovoort.

Bijvoorbeeld,

URL-versiebeheer: https://example-api.com/v1/resource

Queryparameterversie: https://example-api.com/resource?version=v1.

Stap 6: Definieer passende foutmeldingen

Fouten zullen onvermijdelijk optreden tijdens de levensduur van je API. Wat telt, is hoe je die fouten afhandelt. Neem duidelijke en beknopte foutmeldingen op in de responsebody om ontwikkelaars te helpen begrijpen wat er misging.

Voeg informatie toe zoals foutcodes, beschrijvingen en suggesties voor een oplossing. Gebruik standaard HTTP-statuscodes om het slagen of falen van een request aan te geven (bijv. 200 OK voor succes, 404 Not Found wanneer een resource niet is gevonden, 500 Internal Server Error voor serverproblemen).

Stap 7: Houd rekening met onverwacht gedrag

Zorg er ook voor dat je API onverwacht gedrag en requests van eindgebruikers aankan. Zo kunnen eindgebruikers meerdere requests naar dezelfde resource sturen, wat tot simultaneïteitsproblemen kan leiden.

Aan de andere kant kunnen er ook issues aan jouw kant zijn, zoals time-outs en trage responses, of de server geeft een response in een formaat dat de client niet verwacht. Je API moet onverwachte acties op een nette manier kunnen afhandelen met passende foutmeldingen.

Stap 8: Documentatie

Nu je alles hebt gedaan, blijft de documentatie over. Documentatie is als een handleiding die andere ontwikkelaars vertelt hoe je API werkt. Het is een van de belangrijkste factoren die de adoptie en het gebruik van je API beïnvloeden. Zorg er daarom voor dat je documentatie duidelijk, beknopt en eenvoudig te begrijpen is. Enkele best practices:

• Vermijd onnodig technisch jargon dat ontwikkelaars kan verwarren.
• Organiseer je documentatie logisch en hiërarchisch. Gebruik secties, subsecties en koppen zodat gebruikers snel vinden wat ze nodig hebben.
• Neem interactieve voorbeelden of een API-sandbox op, zodat ontwikkelaars direct vanuit de documentatie met de API kunnen experimenteren.
• Overweeg tools zoals Swagger of OpenAPI om interactieve API-documentatie te genereren.

API design first vs code first

Bij het bouwen van een API kun je twee benaderingen volgen: design first of code first.

De strategie die we zojuist bespraken is de design-first-benadering, waarbij je de specificaties van de API definieert, inclusief endpoints, dataformaten, authenticatiemechanismen en de algehele architectuur, voordat je de daadwerkelijke code schrijft die deze specificaties implementeert. Het doel is een duidelijk en doordacht API-design neer te zetten dat aan de eisen van het systeem voldoet en voor ontwikkelaars makkelijk te begrijpen en te gebruiken is.

Bij code first daarentegen begin je met code schrijven zonder de specificaties of documentatie vooraf te definiëren. Ontwikkelaars passen de API gaandeweg aan op basis van hun implementatie-ervaring en feedback uit tests; het ontwerp evolueert terwijl de code wordt geschreven.

Is de ene aanpak beter dan de andere?

Je zou kunnen zeggen dat de code-first-benadering flexibiliteit en ontwikkelsnelheid biedt, omdat snel prototypen mogelijk is. Er zijn echter ook de nodige uitdagingen. Zonder vooraf goed gedefinieerde specificaties bestaat het risico op misverstanden of inconsistenties in hoe verschillende delen van een API worden geïmplementeerd. Uiteindelijk hangt het af van de projectvereisten en de voorkeur van het developmentteam.

Ontdek de creatieve mogelijkheden van API's met DataCamp's gids voor de DALL-E 3 API en leer hoe je AI inzet voor innovatieve oplossingen.

Tot slot

Er zijn allerlei technische aspecten bij het ontwerp van een API. Toch is het goed je API te zien als een product dat je maakt om de pijnpunten van je eindgebruikers op te lossen. Als je API-design wordt gedreven door die pijnpunten, is de kans groter dat hij snel wordt geadopteerd.

Verbeter je technieken voor data-inname via API's met de DataCamp-cursus Streamlined Data Ingestion with pandas. Doe praktische ervaring op met efficiënte data-afhandeling.