API-stijlen en protocollen
Er bestaat geen beste API-stijl. De juiste keuze hangt af van wie de API aanroept, hoeveel data die nodig heeft en hoe snel ze moet aankomen.
Eén vraag, vijf API-stijlen
“Toon klant 1042 met de drie laatste bestellingen.”
GET /customers/1042
200 OK · customer1.2 KB
GET /customers/1042/orders?limit=3
200 OK · 3 orders3.4 KB
Round trips 2
Illustratief voorbeeld
RESTful API's
Representational State Transfer (REST) is de meest gebruikte architectuurstijl voor API's. REST-API's gebruiken standaard HTTP-methoden en zijn stateless, cachebaar en schaalbaar. Meer over best practices voor API-ontwerp.
- Resources en URI's: Resources benoemen met zelfstandige naamwoorden (bijv. /customers, /orders)
- HTTP-methoden: GET, POST, PUT, PATCH, DELETE voor CRUD-operaties
- Statuscodes: Correct gebruik van 2xx-, 4xx- en 5xx-responscodes
- HATEOAS: Hypermedialinks voor vindbaarheid
GraphQL
Querytaal voor API's die clients zelf laat bepalen welke data ze ontvangen. Ideaal voor complexe datavereisten en mobiele applicaties.
- Flexibele queries: Clients specificeren exact welke data ze nodig hebben
- Eén endpoint: Eén endpoint voor alle operaties
- Sterk getypeerd: Schema-first ontwikkeling met typeveiligheid
- Realtime: Ingebouwde ondersteuning voor subscriptions en live-updates
gRPC
Performant RPC-framework op basis van HTTP/2 en Protocol Buffers. Ideaal voor communicatie tussen microservices. Meer over gRPC in ASP.NET Core.
- Binair protocol: Sneller en compacter dan JSON
- Streaming: Client-, server- en bidirectionele streaming
- Codegeneratie: Client- en servercode automatisch genereren uit .proto-bestanden
- Taalonafhankelijk: Ondersteuning voor meerdere programmeertalen
WebSockets & SignalR
Realtime, bidirectionele communicatie voor live-updates. SignalR vereenvoudigt realtime webfunctionaliteit.
- Persistente verbindingen: Langdurige verbindingen voor directe updates
- Pushmeldingen: Door de server geïnitieerde berichten naar clients
- Toepassingen: Chat, dashboards, gaming, samen bewerken
- Terugvalopties: Automatisch terugvallen op Server-Sent Events en daarna long polling als WebSockets niet beschikbaar zijn
OData
Open Data Protocol voor bevraagbare RESTful API's. Veel gebruikt in het Microsoft-ecosysteem (Dynamics 365, SharePoint).
- Querytaal: Filteren, sorteren, pagineren en uitbreiden via de URL
- Metadata: Zelfbeschrijvende API's met een $metadata-endpoint
- Batchbewerkingen: Meerdere bewerkingen in één request versturen
- Deltaqueries: Alleen de data ophalen die sinds de laatste query gewijzigd is
Technologieën voor API-ontwikkeling
Standaard kiezen we voor de Microsoft-stack, en voor andere runtimes waar het team of de workload daarom vraagt.
ASP.NET Core Web API
Modern, cross-platform framework voor het bouwen van HTTP-services. Meer over ASP.NET Core Web API.
Belangrijkste functies
- Minimal APIs: Vereenvoudigde syntaxis voor kleine microservices
- Controllers: Volledig MVC-patroon voor complexe API's
- Model binding: Automatische parameterbinding vanuit routes, querystrings en body
- Validatie: Ondersteuning voor data annotations en FluentValidation
- Dependency injection: Ingebouwde DI-container
- Middlewarepipeline: Uitbreidbare pipeline voor het verwerken van requests
Integratie met OpenAPI (Swagger)
API-documentatie automatisch genereren met de ingebouwde ondersteuning (Microsoft.AspNetCore.OpenApi, sinds .NET 9) en een UI zoals Scalar of Swashbuckle:
- Interactieve API-documentatie (Swagger UI)
- Client-SDK's genereren voor meerdere talen
- Ondersteuning voor API-versiebeheer
- XML-commentaar voor gedetailleerde beschrijvingen van bewerkingen
Azure Functions (serverless API's)
Event-driven, serverless rekenkracht voor API's met een HTTP-trigger. Meer over Azure Functions.
Wanneer kiest u voor Azure Functions?
- Event-driven workloads: Berichten uit wachtrijen, blob-uploads en databasewijzigingen verwerken
- Geplande taken: Cron-gebaseerde achtergrondtaken
- Lichte API's: Eenvoudige HTTP-endpoints zonder complexe routing
- Kostenoptimalisatie: Alleen betalen voor uitvoeringstijd (Consumption-plan)
- Automatisch schalen: Automatisch horizontaal schalen op basis van de belasting
Node.js (Express, NestJS, Fastify)
- Express: Minimalistisch, flexibel framework voor snelle API-ontwikkeling
- NestJS: TypeScript-first framework voor bedrijfstoepassingen met een architectuur zoals Angular
- Fastify: Performant framework, gericht op snelheid en weinig overhead
Python (FastAPI, Django REST Framework)
- FastAPI: Modern, asynchroon framework met automatische OpenAPI-generatie
- Django REST Framework: Krachtige toolkit voor het bouwen van web-API's met Django