Een API-endpoint, of eindpunt, is het precieze adres waar een API verzoeken ontvangt en antwoorden terugstuurt. Het is het punt waar een applicatie verbinding maakt met een server om gegevens op te vragen of een opdracht te starten. In een handleiding die op haar blog is gepubliceerd, legt het bedrijf ElevenLabs deze werking uit aan de hand van haar interface ElevenAPI.
- Een API-endpoint is het adres waar een API verzoeken ontvangt en antwoorden terugstuurt.
- Een REST API gebruikt GET om gegevens te lezen en POST om gegevens te maken of acties te starten.
- Geheime sleutels blijven op beveiligde servers en worden meegestuurd in de header xi-api-key.
- Test een endpoint eerst met een GET-verzoek naar de modellenlijst om authenticatie en netwerktoegang te controleren.
Verzoeken, antwoorden en routes
Een endpoint is een digitale locatie die een API gebruikt om verzoeken te ontvangen en antwoorden terug te sturen. Clientapplicaties hebben toegang tot de bronnen van de server via een URL die aan dit endpoint is gekoppeld. Elke route koppelt een HTTP-methode, het communicatieprotocol van het web, aan een bronpad.
De uitwisseling volgt doorgaans vier stappen. De client stuurt eerst een HTTP-verzoek met daarin een methode, headers, eventueel parameters en een datalichaam. De server controleert de inloggegevens en toegangsrechten, en raadpleegt vervolgens zijn databases of voert de bedrijfslogica uit. Vervolgens stuurt het een payload terug in JSON-formaat, een gestructureerd gegevensformaat, vergezeld van een HTTP-statuscode. De clientapplicatie gebruikt deze gegevens ten slotte.
De termen API, endpoint en URL worden vaak samen gebruikt, maar ze betekenen niet hetzelfde. Een API is de verzameling regels en data-overeenkomsten die twee applicaties in staat stellen te communiceren. Een endpoint is daar een specifiek toegangspunt van, terwijl de URL het volledige geschreven adres is om het op het netwerk te lokaliseren. Een API bevat meerdere endpoints, en een URL kan een protocol, een domeinnaam, een pad en queryparameters bevatten.
In een REST API lezen GET-verzoeken gegevens zonder de bronnen van de server te wijzigen, terwijl POST-verzoeken deze creëren of acties activeren. PUT- of PATCH-verzoeken worden gebruikt om bestaande records te wijzigen, en DELETE om ze te verwijderen. Volgens de handleiding is ElevenAPI voornamelijk gebaseerd op GET en POST, waaraan streaming- en WebSocket-endpoints voor realtime audio worden toegevoegd. Zo haalt het GET-verzoek https://api.elevenlabs.io/v1/models de lijst met beschikbare spraaksynthesemodellen en hun mogelijkheden op. Het POST-verzoek https://api.elevenlabs.io/v1/text-to-speech/{voice_id} stuurt een tekst en een model-ID, en retourneert audio via streaming.
Endpoints beveiligen
Elk verzoek transporteert de geheime sleutel in de header xi-api-key. Deze sleutels op lange termijn moeten op beveiligde servers blijven en nooit verschijnen in client-side code, zoals in een browser of mobiele app. Voor client-side WebSocket-verbindingen genereert de server een eenmalig token, dat na 15 minuten verloopt en bij het eerste gebruik wordt verbruikt.
De handleiding raadt ook aan om aparte sleutels aan te maken voor ontwikkeling, preproductie en productie. Elke sleutel kan worden beperkt tot bepaalde endpoints, bijvoorbeeld tot spraaktranscriptie voor een sleutel die geen synthese nodig heeft. Er kunnen kredietquota per sleutel worden ingesteld, en zakelijke accounts kunnen het gebruik beperken tot bepaalde IP-adressen, een functie die als preview wordt gepresenteerd. Verzoeken vanaf een ander adres worden dan afgewezen met een HTTP 403-fout. De snelheidslimieten zijn, volgens de bron, gebaseerd op gelijktijdigheid, dat wil zeggen het aantal gelijktijdige generaties, en niet op een quotum per minuut.
Testen en monitoren
Een endpoint vanaf het begin testen maakt het mogelijk authenticatie en connectiviteit te verifiëren voordat de applicatielogica wordt geschreven. Een GET-verzoek naar https://api.elevenlabs.io/v1/models, met de header xi-api-key, volstaat om de inloggegevens en netwerktoegang te valideren. Volgens de handleiding verbruikt deze test geen factureerbare credits op het account.
Ook moeten HTTP 429-fouten worden gemonitord. Een too_many_concurrent_requests-fout betekent dat het account de gelijktijdigheidslimiet van zijn abonnement heeft bereikt: wacht tot de lopende verzoeken zijn voltooid of stap over op een hoger abonnement. Een system_busy-fout duidt daarentegen op een tijdelijke overbelasting van het platform, en een nieuwe poging slaagt meestal.
