Een clientgenerator bespaart je het kopiëren van endpointpaden en requestvelden naar je eigen library. Hij kan ook modellen produceren die onjuiste invoer opvangen voordat een request je applicatie verlaat.
Waar vind ik de spec van Bird?
Download de publieke specificatie in JSON of YAML.
De API-referentie en SDK-generatoren van Bird gebruiken ook de publieke bundel. Sla het gedownloade bestand op bij je generatieconfiguratie, zodat je de client later kunt reproduceren.
De OpenAPI-specificatie definieert hoe paden, parameters, authenticatie en responsevormen worden beschreven. Je generator gebruikt die beschrijving om methoden en modellen te bouwen voor zijn doeltaal.
Hoe genereer ik een client?
Gebruik OpenAPI Generator om een client te produceren uit de JSON-spec van Bird. Installeer de tool voordat je de download-, validatie- en generatieopdrachten uitvoert.
Dit voorbeeld genereert een Ruby-client in bird-client:
curl --fail --location https://bird.com/openapi.json --output bird-openapi.json
openapi-generator-cli validate -i bird-openapi.json
openapi-generator-cli generate -i bird-openapi.json -g ruby -o bird-clientGebruik JSON om de YAML-parsergroottelimiet van de generator te omzeilen. Validatie kan aanbevelingen afdrukken, ook als ze slaagt. Bekijk fouten voordat je genereert.
Vervang ruby door een ondersteunde generator voor een andere taal. Volg de installatievereisten van die generator en de gegenereerde README om de output te bouwen of te installeren.
Houd de gegenereerde bestanden gescheiden van handgeschreven applicatiecode. Opnieuw genereren in die map kan bewerkingen overschrijven die je direct in de client hebt aangebracht.
De gebruikshandleiding van de generator documenteert taalopties en configuratiebestanden.
Welke operaties dekt de client?
De client dekt de HTTP-operaties in de publieke bundel van Bird. Een operatie op een ander oppervlak krijgt geen methode via publieke-clientgeneratie.
API-sleutelrotatie is bijvoorbeeld beschikbaar via een dashboardsessie of een persoonlijke CLI- of MCP-toekenning. Die ontbreekt in de publieke bundel en kan niet worden aangeroepen met een werkruimte-API-sleutel.
Tolvrije verificatie heeft ook CLI- en MCP-operaties buiten de publieke bundel. Controleer die oppervlakken voordat je concludeert dat een ontbrekende methode handmatig werk vereist.
Realtime publiceren is een publieke HTTP-operatie. Abonneren op kanaalgebeurtenissen vereist een WebSocket-verbinding. Gebruik hiervoor een Realtime-client.
Welke requestafhandeling moet ik controleren?
Inspecteer de gegenereerde runtime voordat je de ontbrekende afhandeling toevoegt. Verschillende generatoren en configuraties leveren verschillend gedrag.
| Aandachtspunt | Wat je moet controleren |
|---|---|
| Regio | De geselecteerde host komt overeen met de regio in het prefix van je sleutel. |
| Idempotentie | Eén sleutel wordt hergebruikt bij pogingen van dezelfde schrijfactie. |
| Retries | Tijdelijke fouten hebben begrensde retries die Retry-After respecteren. |
| Paginatie | Iteratie volgt cursors totdat er geen volgende pagina meer is. |
| Webhooks | Verificatie gebruikt de ongewijzigde requestbody en controleert de handtekening vóór het parsen. |
Een gegenereerde parameter beheert niet per se de waarde voor je. Een Idempotency-Key-veld heeft nog steeds een sleutel met de juiste levensduur nodig, tenzij de runtime er een levert.
Een configureerbare serverregio bewijst ook niet dat de client die uit je credential leest. Stel de host in of verifieer hem voordat je een request doet.
Moet ik een client genereren of een Bird SDK gebruiken?
Gebruik een Bird SDK als de ondersteunde taal en afhankelijkheden bij je applicatie passen. Genereer een client als je een andere taal nodig hebt of de generatieconventies van je organisatie wilt volgen.
SDK of directe API-aanroepen vergelijkt de ondersteunde talen, het retrygedrag en de standaard time-outs.
- Bird SDK: gebruik de requestafhandeling die Bird levert en onderhoudt.
- Gegenereerde client: kies je taal en controleer de runtime-afhandeling vóór deployment.
- Alleen gegenereerde types: houd de requestafhandeling in je bestaande HTTP-laag.
Kort gezegd
Download de publieke specificatie.
Bird publiceert dezelfde API-beschrijving als YAML en JSON. Het JSON-formaat omzeilt de YAML-groottelimiet van de generator.
Genereer voor je doeltaal.
OpenAPI Generator valideert het gedownloade JSON voordat de client wordt gegenereerd.
Controleer de gegenereerde requestafhandeling.
Controleer regioselectie, retries, idempotentie, paginatie en webhookverificatie voordat je op de client vertrouwt.
Controleer een ander oppervlak op ontbrekende operaties.
API-sleutelrotatie gebruikt een dashboardsessie of een persoonlijke CLI- of MCP-toekenning. Realtime-abonnementen vereisen een WebSocket-client.