Generator client menghemat waktu Anda dari menyalin path endpoint dan field request ke library Anda sendiri. Generator juga dapat menghasilkan model yang menangkap input salah sebelum request meninggalkan aplikasi Anda.
Di mana saya mendapatkan spec Bird?
Unduh spesifikasi publik dalam format JSON atau YAML.
Referensi API dan generator SDK milik Bird juga menggunakan bundle publik. Simpan file yang diunduh bersama konfigurasi pembuatan Anda agar Anda dapat mereproduksi client nanti.
Spesifikasi OpenAPI mendefinisikan cara mendeskripsikan path, parameter, autentikasi, dan bentuk response. Generator Anda menggunakan deskripsi tersebut untuk membuat method dan model bagi bahasa targetnya.
Bagaimana cara membuat client?
Gunakan OpenAPI Generator untuk membuat client dari spec JSON milik Bird. Instal tool ini sebelum menjalankan perintah unduh, validasi, dan pembuatan.
Contoh ini membuat client Ruby di 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-clientGunakan JSON untuk menghindari batas ukuran YAML parser pada generator. Validasi dapat mencetak rekomendasi meskipun berhasil. Tinjau error sebelum membuat client.
Ganti ruby dengan generator yang didukung untuk bahasa lain. Ikuti persyaratan instalasi generator tersebut dan README yang dihasilkan untuk mem-build atau menginstal output.
Pisahkan file yang dihasilkan dari kode aplikasi yang ditulis manual. Regenerasi ke direktori tersebut dapat menimpa perubahan yang Anda buat langsung pada client.
Panduan penggunaan generator mendokumentasikan opsi bahasa dan file konfigurasi.
Operasi apa saja yang dicakup client?
Client mencakup operasi HTTP yang termasuk dalam bundle publik Bird. Operasi pada surface lain tidak akan mendapatkan method melalui pembuatan client publik.
Contohnya, rotasi API-key tersedia melalui sesi dashboard atau grant CLI atau MCP personal. Operasi ini tidak ada dalam bundle publik dan tidak dapat dipanggil dengan workspace API key.
Verifikasi toll-free juga memiliki operasi CLI dan MCP di luar bundle publik. Periksa surface tersebut sebelum menyimpulkan bahwa method yang tidak tersedia memerlukan pekerjaan manual.
Realtime publishing adalah operasi HTTP publik. Berlangganan event channel memerlukan koneksi WebSocket. Gunakan client Realtime untuk bagian tersebut.
Penanganan request apa yang harus saya periksa?
Periksa runtime yang dihasilkan sebelum menambahkan penanganan yang belum tersedia. Generator dan konfigurasi yang berbeda menyediakan perilaku yang berbeda.
| Aspek | Yang perlu diverifikasi |
|---|---|
| Region | Host yang dipilih sesuai dengan region pada prefix key Anda. |
| Idempotensi | Satu key digunakan ulang untuk seluruh percobaan write yang sama. |
| Retry | Kegagalan sementara memiliki retry terbatas yang mematuhi Retry-After. |
| Paginasi | Iterasi mengikuti cursor sampai tidak ada halaman berikutnya. |
| Webhook | Verifikasi menggunakan body request yang tidak diubah dan memeriksa signature sebelum parsing. |
Parameter yang dihasilkan belum tentu mengelola nilainya untuk Anda. Field Idempotency-Key tetap memerlukan key dengan masa berlaku yang tepat kecuali runtime menyediakannya.
Demikian pula, region server yang dapat dikonfigurasi tidak membuktikan bahwa client membacanya dari kredensial Anda. Atur atau verifikasi host sebelum membuat request.
Haruskah saya membuat client atau menggunakan Bird SDK?
Gunakan Bird SDK jika bahasa dan dependensi yang didukungnya sesuai dengan aplikasi Anda. Buat client jika Anda memerlukan bahasa lain atau konvensi pembuatan organisasi Anda.
SDK atau panggilan API langsung membandingkan bahasa yang didukung, perilaku retry, dan default timeout.
- Bird SDK: gunakan penanganan request yang disediakan dan dipelihara Bird.
- Generated client: pilih bahasa Anda dan tinjau penanganan runtime-nya sebelum deployment.
- Generated types only: pertahankan penanganan request di layer HTTP Anda yang sudah ada.
Singkatnya
Unduh spesifikasi publik.
Bird menerbitkan deskripsi API yang sama dalam format YAML dan JSON. Format JSON menghindari batas ukuran YAML pada generator.
Buat client untuk bahasa target Anda.
OpenAPI Generator memvalidasi JSON yang diunduh sebelum membuat client.
Periksa penanganan request yang dihasilkan.
Tinjau pemilihan region, retry, idempotensi, paginasi, dan verifikasi webhook sebelum mengandalkan client.
Periksa surface lain untuk operasi yang tidak tersedia.
Rotasi API-key menggunakan sesi dashboard atau grant CLI atau MCP personal. Langganan Realtime memerlukan client WebSocket.