Pindah ke alamat API

Integrasi lama memanggil API di alamat utama Sursa, alamat yang dibuka orang di peramban, misalnya https://app.sursa.com/v1/…. Kini API juga memiliki alamatnya sendiri, https://api.sursa.com di cloud atau https://api.<your domain> di instalasi Anda. Alamat ini dibuat untuk integrasi: dapat diskalakan dengan server tambahan di belakang load balancer, dan tidak melayani apa pun selain API.

Anda tidak wajib pindah. Alamat utama tetap melayani /v1 untuk integrasi yang sudah ada, tanpa tanggal akhir dan tanpa pengalihan. Pindahlah saat sesuai bagi Anda, untuk mendapatkan manfaat alamat API, dan pakai alamat itu untuk setiap integrasi baru.

Apa yang tetap sama

Path, parameter, field, kode error, dan peristiwa: GET /v1/cards adalah permintaan yang sama di kedua alamat.
Kunci API. Kunci kb_ dan kbsrc_ yang sama berfungsi di kedua alamat, dengan peran, cakupan, dan profil data yang sama.
Kunci idempotensi, batas laju, dan kuota. Permintaan di kedua alamat dihitung terhadap kuota organisasi yang sama.
Webhook. Pengiriman, tanda tangan, dan rahasia tidak bergantung pada alamat yang Anda panggil.
Tautan dalam respons. doc_url dari error mengarah ke portal ini, dan header Link dari halaman daftar mengarah ke alamat API, alamat mana pun yang Anda panggil.

Apa yang berbeda di alamat API

Di alamat utama	Di alamat API
Setiap endpoint aplikasi web, termasuk endpoint internal	Hanya endpoint dari referensi API publik. Path lain apa pun menjawab `404` dengan kode `api.not_found`.
Kunci di `X-API-Key` atau `Authorization`, atau cookie sesi peramban	Kunci atau token akses OAuth, sebaiknya di `Authorization: Bearer`. Cookie diabaikan.
`GET /auth/me`	`GET /v1/me`. Path di bawah `/auth/` tidak dilayani.
Mode “View as” (Lihat sebagai) melalui cookie	Header `X-View-As`, untuk kunci dengan peran `admin`.
Satu server, atau kumpulan server yang tetap	Beberapa server di belakang load balancer.

Baris terakhir hanya penting untuk satu kasus: jawaban stream dari POST /v1/chat. Stream yang terputus hanya berlanjut dari Last-Event-ID di server yang menulis jawabannya. Jika integrasi Anda melanjutkan stream, berikan setiap pertanyaan request_id, agar percobaan ulang di server lain menerima jawaban yang tersimpan, bukan jawaban kedua. Lihat Melanjutkan stream yang terputus.

Sebelum Anda pindah

Periksa bahwa setiap panggilan bersifat publik. Buat daftar path yang dipanggil integrasi Anda dan cari masing-masing di referensi API, atau bandingkan dengan spesifikasi alamat baru:

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

Path yang tidak ada di referensi publik adalah milik aplikasi web. Path itu masih berfungsi di alamat utama, tetapi tidak dilayani di alamat API, dan bentuknya bukan komitmen publik. Ganti dengan endpoint publik, atau pertahankan bagian integrasi itu di alamat utama dan beri tahu kontak Anda di Sursa apa yang Anda butuhkan.

Periksa cara Anda melakukan autentikasi. Jika integrasi masuk dengan kata sandi pengguna dan cookie sesi, pindahkan dulu ke kunci API. Jika integrasi mengirim X-API-Key, beralih ke Authorization: Bearer dianjurkan tetapi tidak wajib.

Periksa jaringan Anda. Izinkan HTTPS keluar ke nama host baru di firewall dan proxy Anda.

Pindah langkah demi langkah

Jadikan URL dasar sebagai pengaturan integrasi Anda, jika belum.

Coba alamat baru dengan permintaan baca:

curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"

Jalankan rangkaian pengujian integrasi Anda terhadap alamat baru, dengan kunci uji dan koleksi uji.
Alihkan sebagian lalu lintas, misalnya satu worker atau satu lingkungan, dan perhatikan 404 api.not_found, 401, dan 5xx di log Anda. Setiap respons membawa X-Request-Id; simpan nilai itu bersama log Anda.
Alihkan sisanya. Simpan URL dasar lama di konfigurasi Anda untuk sementara agar Anda dapat beralih kembali dalam hitungan detik.

Yang perlu diperiksa setelah pindah

GET /v1/health di alamat baru mengembalikan version yang sama dengan di alamat lama.
Header RateLimit ada di respons. Jika integrasi Anda memperlambat dirinya sendiri menurut X-RateLimit-*, integrasi itu dapat terus melakukannya: kedua kumpulan header dikirim. Lihat Batas laju dan kuota.
Jika integrasi Anda berjalan di peramban, integrasi itu tidak lagi membutuhkan proxy Anda sendiri untuk CORS: alamat API mengizinkan permintaan dari origin mana pun, tanpa cookie.