Alamat API dan lingkungan

API Sursa memiliki alamatnya sendiri, terpisah dari alamat yang dipakai orang untuk membuka Sursa di peramban. Semua path diawali dengan /v1.

Tempat Sursa berjalan	Alamat API	Portal ini
Cloud Sursa	`https://api.sursa.com`	`https://developers.sursa.com`
Instalasi Anda sendiri	`https://api.<your domain>`, sesuai pengaturan administrator Anda	`/developers/` di alamat API
Instalasi Anda tanpa alamat API terpisah	alamat utama instalasi	`/developers/` di alamat utama

Alamat API hanya melayani API: di sana tidak ada halaman masuk, cookie, atau antarmuka web. Setiap permintaan diautentikasi dengan kunci API atau token akses OAuth. Alamat itu dapat dilayani oleh beberapa server di belakang load balancer; integrasi Anda tidak perlu tahu berapa jumlahnya.

Integrasi yang memanggil API di alamat utama (misalnya https://app.sursa.com/v1) tetap berfungsi. Lihat Pindah ke alamat API untuk beberapa perbedaannya dan cara pindah langkah demi langkah.

URL dasar

Bangun setiap permintaan dari satu URL dasar di konfigurasi Anda, agar kode yang sama berjalan di lingkungan mana pun:

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

Pakai hanya HTTPS, dan jauhkan kunci dari log permintaan yang Anda kirim.

Versi dan spesifikasi

GET /v1/health menunjukkan apakah alamat itu aktif dan mengembalikan versi Sursa yang melayaninya. Endpoint ini menjawab tanpa kunci, jadi Anda dapat memakainya untuk pemantauan:

curl https://api.sursa.com/v1/health

{"ok": true, "version": "v1.4.0"}

Ini adalah versi rilis Sursa, bukan versi API. Versi API adalah info.version dari spesifikasinya. Spesifikasi OpenAPI 3.1 API dipublikasikan di alamat yang sama, tanpa autentikasi:

Path	Isi
`GET /openapi.json`	Spesifikasi publik, dengan alamat ini di `servers`.
`GET /v1/openapi-public.json`	Spesifikasi yang sama. Mendukung `ETag` dan `If-None-Match`.

Pakai spesifikasi ini untuk menghasilkan klien, mengimpor API ke alat seperti Postman, atau memeriksa di CI bahwa integrasi Anda hanya memakai operasi dari versi yang Anda harapkan. Referensi API di portal ini dibangun dari file yang sama.

Pengujian

Sursa tidak memiliki mode uji terpisah: setiap permintaan dengan kunci bekerja pada data asli organisasinya. Untuk mengembangkan dan menguji dengan aman:

Buat kunci terpisah untuk pengembangan dengan peran dan cakupan tersempit yang dibutuhkan pekerjaan itu.
Tulis ke koleksi khusus, misalnya sandbox, yang hanya dapat dilihat tim Anda, dan hapus koleksi itu setelah selesai.
Jika perusahaan Anda memiliki organisasi atau instalasi Sursa terpisah untuk pengujian, arahkan URL dasar dan kunci ke sana. Tidak ada hal lain yang berubah dalam kode Anda.
Buat percobaan ulang aman sejak awal: kirim Idempotency-Key bersama setiap POST dan PATCH.

Konsol Coba di setiap halaman endpoint di referensi API mengirim permintaan sungguhan dengan kunci yang Anda tempelkan ke dalamnya. Kunci tetap berada di memori tab peramban dan hanya dikirim ke alamat API.

Persyaratan jaringan

HTTPS keluar (port 443) dari server Anda ke alamat API.
Izinkan nama host, bukan alamat IP tetap, dalam aturan firewall jika jaringan Anda memungkinkan: server di belakang alamat itu dapat berubah saat kapasitas ditambah.
Aplikasi peramban dapat memanggil API secara langsung: respons mengizinkan origin mana pun (Access-Control-Allow-Origin: *) tanpa cookie. Ingat bahwa kunci yang dipakai di peramban terlihat oleh pengguna peramban tersebut.