Een endpoint is een specifiek adres binnen een API dat een applicatie aanroept om één bepaald ding te doen. Waar de API het hele menu is van wat een systeem kan aanbieden, is een endpoint één item op dat menu, zoals haal deze klant op of maak die bestelling aan. Het is bijna altijd een URL gekoppeld aan een actie.
Denk aan een groot kantoorgebouw met één centrale receptie. Het gebouw is de API, maar binnen zitten allerlei deuren, elk met een afdeling erop: salaris, sales, support. Je loopt niet de salarisafdeling binnen voor een salesvraag. Een endpoint is zo’n gelabelde deur: je stuurt je verzoek naar de juiste en krijgt precies de data terug die je vroeg, meestal als JSON.
In een REST API kan hetzelfde adres zich anders gedragen, afhankelijk van het werkwoord dat je gebruikt. Een GET naar /api/klanten/42 leest die klant, een PUT werkt hem bij, een DELETE verwijdert hem, allemaal op dezelfde URL. Dat houdt het ontwerp netjes en voorspelbaar.
Een endpoint is ook een afspraak, en dat heeft gevolgen. Andere systemen gaan rekenen op het precieze adres, de velden die het teruggeeft en de vorm van die velden. Hernoem je het of laat je stilletjes een veld vallen, dan breek je elke app die het aanriep, vaak zonder waarschuwing. Daarom geven teams hun API’s versies: ze publiceren /v2/ naast de oude /v1/ in plaats van er eentje ter plekke te wijzigen, zodat bestaande koppelingen blijven werken terwijl nieuwe verdergaan.
Bij TopDevs ontwerpen we heldere, goed benoemde endpoints, zodat de systemen die we bouwen makkelijk te koppelen zijn voor andere developers, en andere tools, zonder giswerk.
