Bagaimana API Optifora berfungsi
Halaman ini menerangkan bentuk API: bagaimana identiti dibuktikan, bagaimana versi bergerak ke hadapan, had mana yang perlu dipatuhi oleh sesuatu permintaan, rupa sesuatu ralat, dan bagaimana data dipertukarkan dengan dunia luar.
Produk ini masih dalam pembangunan dan permukaan API-nya masih dilengkapkan. Dokumen rujukan bagi titik akhir akan diterbitkan secara berasingan; halaman ini tidak membawa sebarang alamat mahupun contoh panggilan, hanya mekanismenya.
Pengesahan identiti
Setiap permintaan adalah milik seseorang atau milik sebuah aplikasi yang berdaftar. Permintaan tanpa identiti yang sampai ke titik akhir terlindung akan kembali sebagai tidak disahkan.
- Token BearerToken capaian dibawa dalam pengepala kebenaran permintaan. Ia ditandatangani, dan ia hanya menyatakan permintaan itu milik siapa.
- Hayat pendekToken capaian luput selepas tempoh yang diukur dalam minit; panjang tempoh itu ialah tetapan pemasangan dan lalainya tiga puluh minit.
- Pembaharuan dan penggiliranSesi dilanjutkan dengan token pembaharuan, dan setiap lanjutan mengeluarkan pasangan baharu. Jika token pembaharuan yang sudah terpakai dikemukakan kali kedua, semua sesi bagi orang itu ditarik balik.
- Kebenaran tidak ditanam di dalam tokenToken hanya membawa identiti; apa yang boleh dilihat oleh seseorang ditanya kepada pangkalan data pada setiap permintaan. Kebenaran yang ditarik balik oleh itu berhenti berfungsi sebelum token yang ada di tangan luput.
- Kunci penyepaduAplikasi yang berdaftar berhubung dengan kuncinya sendiri. Nilai asal dipaparkan sekali sahaja, semasa ia dijana; yang disimpan ialah nilai cincangannya dan awalan bukan rahsia yang membolehkan sesuatu kunci dikenali.
- Organisasi yang memberi capaianSebanyak mana pun sesuatu aplikasi digunakan, tanpa kebenaran yang direkodkan oleh organisasi ia tidak melihat satu baris pun. Kebenaran itu bertarikh, berskop dan boleh ditarik balik.
Penomboran versi
- Versi berada dalam laluanTitik akhir diterbitkan di belakang awalan versi; permukaan hari ini ialah versi satu.
- Perubahan yang memecahkan keserasian membuka laluan baharuKontrak titik akhir yang sedia ada tidak dipecahkan di tempatnya. Perubahan yang tidak serasi diterbitkan pada laluan versi baharu sementara yang lama terus berfungsi.
- Dokumen menyatakan versinya sendiriRujukan membawa nombor versi yang menjadi asas penjanaannya; versi mana yang sedang anda baca dijawab oleh dokumen itu sendiri.
Persekitaran dan had
Rujukan ini mengisytiharkan dua persekitaran: pengeluaran dan pembangunan setempat. Alamat akarnya diserahkan kepada penyepadu bersama kuncinya; ia tidak diterbitkan di halaman ini.
- Kehidupan dan kesediaan diukur secara berasinganSatu titik akhir menyatakan proses itu hidup; yang kedua menghantar pertanyaan sebenar ke pangkalan data dan mengesahkan ia boleh dicapai. Hanya yang kedua menentukan sama ada trafik patut dihantar.
- Asalan pelayar dihadkan kepada satu senaraiPermintaan silang asalan diterima hanya daripada asalan yang diisytiharkan lebih awal; selagi senarai itu kosong, permintaan pelayar dari asalan lain akan ditolak.
- Had saiz badan permintaanBadan permintaan tidak boleh melebihi lima megabait. Set yang besar bergerak sebagai kerja pemindahan pukal dengan rekod statusnya sendiri, bukan sebagai satu permintaan tunggal.
- Rahsia tidak ditulis ke dalam logLog pelayan tidak menyimpan pengepala kebenaran, kuki, kata laluan mahupun nombor pengenalan diri.
Had kadar
Had dikira mengikut alamat dan mengikut minit. Nilai lalainya 120 permintaan seminit dan ia ditetapkan semasa pemasangan. Baki yang tinggal dilaporkan dalam pengepala pada setiap respons.
| Pengepala respons | Apa yang dinyatakannya |
|---|---|
| x-ratelimit-limit | Jumlah peruntukan di dalam tetingkap tersebut. |
| x-ratelimit-remaining | Berapa banyak yang tinggal dalam tetingkap ini. |
| x-ratelimit-reset | Berapa saat lagi sebelum peruntukan diperbaharui. |
| retry-after | Berapa saat sebelum percubaan semula. Hadir hanya pada respons yang menolak permintaan. |
Sebaik had dilampaui, permintaan ditolak dan respons menyatakan berapa saat perlu menunggu. Percubaan semula dibuat selepas tempoh itu, bukan serta-merta.
Format ralat
Setiap ralat kembali dalam sampul yang sama: satu medan kod ringkas untuk mesin membuat percabangan, dan satu medan penerangan untuk dibaca oleh manusia.
- errorKod ringkas yang menjadi asas keputusan klien.
- messagePenerangan tentang apa yang berlaku.
| Status | Medan kod | Maksudnya |
|---|---|---|
| 400 | Bad Request | Permintaan tidak menepati skema. Penerangannya menamakan medan yang tiada atau tidak sah. |
| 401 | unauthenticated | Tiada identiti yang sah: tiada token dihantar, ia telah luput, atau ia tidak lulus pengesahan. |
| 404 | Not Found | Tiada titik akhir sedemikian, atau tiada rekod sedemikian. |
| 429 | Too Many Requests | Had kadar telah dilampaui; respons menyatakan berapa lama perlu menunggu. |
| 5xx | internal_error | Kegagalan yang tidak dijangka. Butirannya tidak diserahkan kepada klien; ia ditulis ke dalam log pelayan. |
Penomboran halaman
Titik akhir yang memulangkan senarai menerima dua parameter yang sama dan memulangkan pembilang yang sama, jadi klien penomboran halaman tidak perlu ditulis semula bagi setiap titik akhir.
- limitBerapa banyak rekod yang patut dimuatkan dalam satu halaman. Sekurang-kurangnya satu, paling banyak dua ratus; lima puluh apabila tidak ditetapkan.
- offsetBerapa banyak rekod yang perlu dilangkau. Bermula dari sifar.
- totalBerapa banyak rekod yang menepati penapis secara keseluruhan.
- countBerapa banyak rekod yang benar-benar dibawa oleh respons ini.
Respons juga mengulang semula nilai limit dan offset yang digunakannya; klien membaca kedudukannya daripada jawapan dan tidak perlu menekanya.
Pertukaran data dan webhook
Mod pertukaran ialah satu tetapan, bukan produk yang berasingan: setiap aplikasi berdaftar membawa mod operasinya pada rekodnya sendiri.
| Mod | Maksudnya |
|---|---|
| Sehala — keluar | Optifora menerbitkan data; pihak yang satu lagi membacanya atau melanggan peristiwanya. |
| Sehala — masuk | Pihak yang satu lagi menolak data masuk; Optifora mengesahkan kesahihannya dan menulisnya. |
| Dua hala | Kedua-dua pihak menulis; peraturan penyelesaian percanggahan ditakrifkan lebih awal. |
| Jabat tangan | Setiap pemindahan membuka satu sesi: tawaran, pengesahan, kelulusan, pemindahan dan resit. Resit itu kekal pada kedua-dua pihak. |
- Peristiwa ditolak keluarWebhook menghantar peristiwa itu ke alamat panggil balik yang diisytiharkan oleh aplikasi berdaftar. Peristiwa yang tidak dapat dihantar kekal dalam baris gilir dan dicuba semula; ia tidak pernah digugurkan secara senyap.
- Permintaan yang sama tidak menulis dua kaliPermintaan tulis membawa kunci idempoten. Permintaan kedua dengan kunci yang sama tidak mencipta rekod kedua.
- Setiap panggilan diukurSiapa yang memanggil, bila, dengan skop apa dan dengan hasil apa — semuanya direkodkan. Rekod yang sama menjawab kerja penyahpepijatan dan juga soalan siapa yang menarik data ini.
- Aplikasi kami sendiri menggunakan pintu yang samaTiada laluan kedua yang beristimewa. Penyepaduan kami sendiri ialah bukti bagi permukaan yang ditemui oleh pembangun luar.
Model data bagi lapisan pertukaran sudah sedia; titik akhirnya belum diterbitkan. Apabila ia diterbitkan, bahagian ini akan memaut kepada entrinya di dalam rujukan.
Dokumen rujukan
Rujukan ini tidak ditulis dengan tangan; ia dijana daripada skema titik akhir. Sebaik setiap titik akhir menyerahkan skemanya, dokumen itu terisi dengan sendirinya, jadi dokumen dan tingkah laku sebenar tidak boleh terpesong antara satu sama lain.
- Hari ini: dalam persediaanSkema sedang bergerak modul demi modul. Sebelum dokumen itu diterbitkan, permintaan dan respons setiap titik akhir akan kelihatan di dalamnya.
- Dua format akan diterbitkanSatu dokumen OpenAPI yang boleh dibaca mesin, dan satu halaman rujukan yang dijana daripada dokumen yang sama dan boleh dilayari dalam pelayar.
- Capaian berperingkatGambaran keseluruhan terbuka kepada sesiapa sahaja. Rujukan penuh mungkin berada di belakang token dokumentasi yang diberikan kepada penyepadu berdaftar; kunci pengeluaran dan alamat panggil balik langsung bukan urusan dokumentasi — ia milik rekod aplikasi itu sendiri.
- Piawai alamatDua rujukan diterbitkan dan alamatnya tetap: client-api.optifora.com/docs terbuka, admin-api.optifora.com/docs memerlukan kebenaran dan tertutup kepada pihak luar. Kedua-duanya belum aktif hari ini; pautannya akan ditambah ke bahagian ini sebaik ia aktif.
Jika rancangan penyepaduan anda sudah jelas, tulislah kepada kami dari halaman hubungi kami: anda antara yang pertama dimaklumkan apabila permukaan ini dibuka.
Anda ada permintaan tertentu?
Halaman ini menerangkan cara proses sokongan berjalan. Jika anda mempunyai permintaan atau pertanyaan, tulislah kepada kami dari halaman hubungi kami.
Pergi ke halaman hubungi kami