Cara kerja API Optifora
Halaman ini menjelaskan bentuk API: bagaimana identitas dibuktikan, bagaimana versi bergerak maju, batas apa yang harus dipatuhi sebuah permintaan, seperti apa rupa sebuah galat, dan bagaimana data dipertukarkan dengan dunia luar.
Produk ini masih dalam pengembangan dan permukaan API-nya masih dirampungkan. Dokumen rujukan untuk endpoint akan diterbitkan terpisah; halaman ini tidak memuat alamat maupun contoh pemanggilan, hanya mekanismenya.
Autentikasi
Setiap permintaan milik seseorang atau milik sebuah aplikasi yang terdaftar. Permintaan tanpa identitas yang mencapai endpoint terlindungi akan kembali sebagai tidak terautentikasi.
- Token bearerToken akses dibawa di header otorisasi permintaan. Token itu ditandatangani, dan hanya menyatakan milik siapa permintaan tersebut.
- Umur pendekToken akses kedaluwarsa setelah jangka waktu yang dihitung dalam menit; panjangnya adalah pengaturan penggelaran dan bawaannya tiga puluh menit.
- Penyegaran dan rotasiSesi diperpanjang dengan token penyegar, dan setiap perpanjangan menerbitkan pasangan yang baru. Jika token penyegar yang sudah terpakai diajukan untuk kedua kalinya, seluruh sesi orang tersebut dicabut.
- Hak akses tidak ditanamkan di dalam tokenToken hanya membawa identitas; apa yang boleh dilihat seseorang ditanyakan ke basis data pada setiap permintaan. Karena itu izin yang ditarik berhenti bekerja sebelum token yang ada di tangan kedaluwarsa.
- Kunci integratorAplikasi yang terdaftar terhubung dengan kuncinya sendiri. Nilai terbukanya ditampilkan satu kali saja, yaitu saat dibuat; yang disimpan adalah ringkasannya dan awalan non-rahasia yang membuat sebuah kunci dapat dikenali.
- Organisasi yang memberikan aksesSepopuler apa pun sebuah aplikasi, tanpa izin yang dicatat oleh organisasi ia tidak melihat satu baris pun. Izin itu bertanggal, terbatas cakupannya dan dapat dicabut.
Pemversian
- Versi berada di dalam jalurEndpoint diterbitkan di balik awalan versi; permukaan hari ini adalah versi satu.
- Perubahan yang merusak membuka jalur baruKontrak sebuah endpoint yang sudah ada tidak dirusak di tempat. Perubahan yang tidak kompatibel diterbitkan pada jalur versi baru sementara yang lama tetap bekerja.
- Dokumen menyatakan versinya sendiriRujukan membawa nomor versi asal pembuatannya; versi mana yang sedang Anda baca dijawab oleh dokumen itu sendiri.
Lingkungan dan batas
Rujukan ini menyatakan dua lingkungan: produksi dan pengembangan lokal. Alamat akarnya diserahkan kepada integrator bersama kuncinya; alamat itu tidak diterbitkan di halaman ini.
- Kehidupan dan kesiapan diukur terpisahSatu endpoint menyatakan bahwa prosesnya hidup; yang kedua mengirim kueri sungguhan ke basis data dan memastikan basis data itu terjangkau. Hanya yang kedua yang menentukan apakah lalu lintas layak dikirim.
- Asal peramban dibatasi pada sebuah daftarPermintaan lintas asal hanya diterima dari asal yang dinyatakan lebih dahulu; selama daftarnya kosong, permintaan lintas asal dari peramban ditolak.
- Batas badan permintaanBadan permintaan tidak boleh melebihi lima megabyte. Kumpulan data besar berjalan sebagai pekerjaan transfer massal dengan catatan statusnya sendiri, bukan sebagai satu permintaan.
- Rahasia tidak ditulis ke logLog server tidak menyimpan header otorisasi, kuki, kata sandi maupun nomor identitas kependudukan.
Batas laju
Batasnya per alamat dan per menit. Bawaannya 120 permintaan per menit dan ditetapkan saat penggelaran. Sisa jatah dilaporkan lewat header pada setiap respons.
| Header respons | Apa yang dinyatakan |
|---|---|
| x-ratelimit-limit | Jatah total di dalam jendela waktu. |
| x-ratelimit-remaining | Sisa jatah pada jendela waktu ini. |
| x-ratelimit-reset | Detik sampai jatah diperbarui. |
| retry-after | Berapa detik sebelum percobaan ulang. Hanya ada pada respons yang menolak permintaan. |
Begitu batas terlampaui, permintaan ditolak dan responsnya menyatakan berapa detik harus menunggu. Percobaan ulang dilakukan setelah waktu itu, bukan seketika.
Format galat
Setiap galat kembali dalam amplop yang sama: sebuah bidang kode pendek agar mesin dapat bercabang, dan sebuah bidang penjelasan agar dapat dibaca manusia.
- errorKode pendek yang menjadi dasar keputusan klien.
- messagePenjelasan tentang apa yang terjadi.
| Status | Bidang kode | Artinya |
|---|---|---|
| 400 | Bad Request | Permintaan tidak sesuai dengan skema. Penjelasannya menyebutkan bidang yang hilang atau tidak sah. |
| 401 | unauthenticated | Tidak ada identitas yang sah: token tidak dikirim, sudah kedaluwarsa, atau tidak terverifikasi. |
| 404 | Not Found | Endpoint seperti itu tidak ada, atau catatan seperti itu tidak ada. |
| 429 | Too Many Requests | Batas laju terlampaui; responsnya menyatakan berapa lama harus menunggu. |
| 5xx | internal_error | Kegagalan yang tidak terduga. Rinciannya tidak diserahkan kepada klien; rincian itu ditulis ke log server. |
Penomoran halaman
Endpoint yang mengembalikan daftar menerima dua parameter yang sama dan mengembalikan penghitung yang sama, sehingga klien penomoran halaman tidak perlu ditulis ulang untuk tiap endpoint.
- limitBerapa banyak catatan yang seharusnya dimuat satu halaman. Paling sedikit satu, paling banyak dua ratus; lima puluh bila tidak ditentukan.
- offsetBerapa banyak catatan yang dilewati. Dimulai dari nol.
- totalBerapa banyak catatan yang cocok dengan seluruh filter.
- countBerapa banyak catatan yang sebenarnya dibawa respons ini.
Respons juga mengulang kembali limit dan offset yang dipakainya; klien membaca posisinya dari jawaban alih-alih menebaknya.
Pertukaran data dan webhook
Mode pertukaran adalah sebuah pengaturan, bukan produk terpisah: setiap aplikasi terdaftar membawa mode kerjanya pada catatannya sendiri.
| Mode | Artinya |
|---|---|
| Satu arah — keluar | Optifora menerbitkan data; pihak lain membacanya atau berlangganan peristiwa. |
| Satu arah — masuk | Pihak lain mendorong data; Optifora memvalidasi lalu menuliskannya. |
| Dua arah | Kedua sisi menulis; aturan penyelesaian konflik ditetapkan di awal. |
| Jabat tangan | Setiap perpindahan data membuka sebuah sesi: penawaran, verifikasi, persetujuan, pengiriman dan tanda terima. Tanda terima itu tersimpan pada kedua sisi. |
- Peristiwa didorong keluarWebhook mengirim peristiwa ke alamat panggilan balik yang dinyatakan aplikasi terdaftar. Peristiwa yang tidak dapat dikirim tetap berada di antrean dan dicoba ulang; peristiwa itu tidak pernah dibuang diam-diam.
- Permintaan yang sama tidak menulis dua kaliPermintaan tulis membawa sebuah kunci idempotensi. Permintaan kedua dengan kunci yang sama tidak membuat catatan kedua.
- Setiap pemanggilan diukurSiapa yang memanggil, kapan, dengan cakupan apa dan dengan hasil apa — semuanya dicatat. Catatan yang sama menjawab kebutuhan penelusuran galat sekaligus pertanyaan siapa yang menarik data ini.
- Aplikasi kami sendiri memakai pintu yang samaTidak ada jalur kedua yang istimewa. Integrasi kami sendiri adalah bukti dari permukaan yang dijumpai pengembang luar.
Model data untuk lapisan pertukaran sudah siap; endpoint-nya belum diterbitkan. Ketika nanti terbit, bagian ini akan menautkan ke entrinya di dalam rujukan.
Dokumen rujukan
Rujukan ini tidak ditulis dengan tangan; ia dihasilkan dari skema endpoint. Setiap kali sebuah endpoint menyerahkan skemanya, dokumen itu terisi dengan sendirinya, sehingga dokumen dan perilaku tidak mungkin berbeda arah.
- Hari ini: dalam persiapanSkema dipindahkan modul demi modul. Sebelum dokumennya terbit, permintaan dan respons setiap endpoint akan tampak di dalamnya.
- Dua format akan diterbitkanSebuah dokumen OpenAPI yang terbaca mesin, dan sebuah halaman rujukan yang ditarik dari dokumen yang sama serta dapat ditelusuri di peramban.
- Akses berjenjangIkhtisarnya terbuka untuk siapa saja. Rujukan lengkapnya dapat berada di balik sebuah token dokumentasi yang diberikan kepada integrator terdaftar; kunci produksi dan alamat panggilan balik sama sekali bukan urusan dokumentasi — keduanya milik catatan aplikasi.
- Standar alamatDua rujukan diterbitkan dan alamatnya tetap: client-api.optifora.com/docs terbuka, admin-api.optifora.com/docs memerlukan otorisasi dan tertutup bagi pihak luar. Keduanya belum aktif hari ini; tautannya akan ditambahkan ke bagian ini begitu aktif.
Jika rencana integrasi Anda sudah jelas, tulislah kepada kami dari halaman kontak: Anda akan termasuk yang pertama diberi tahu ketika permukaannya dibuka.
Punya permintaan tertentu?
Halaman-halaman ini menjelaskan cara kerja proses dukungan. Bila Anda punya permintaan atau pertanyaan, tulislah kepada kami dari halaman kontak.
Buka halaman kontak