Paano gumagana ang API ng Optifora
Inilalarawan ng pahinang ito ang hugis ng API: paano pinatutunayan ang pagkakakilanlan, paano sumusulong ang mga bersyon, anong mga hangganan ang sinusunod ng isang kahilingan, ano ang anyo ng isang error, at paano ipinagpapalit ang datos sa labas ng sistema.
Nasa pagbuo pa ang produkto at pinupunuan pa ang ibabaw ng API. Ilalathala nang hiwalay ang dokumentong sanggunian para sa mga endpoint; walang dalang address at walang halimbawang tawag ang pahinang ito, mekanika lamang.
Pagpapatunay ng pagkakakilanlan
Ang bawat kahilingan ay nabibilang sa isang tao o sa isang nakarehistrong aplikasyon. Ang kahilingang walang pagkakakilanlan na umabot sa protektadong endpoint ay bumabalik na hindi napatunayan.
- Bearer tokenAng access token ay naglalakbay sa authorization header ng kahilingan. Nilagdaan ito, at sinasabi lamang nito kung kanino nabibilang ang kahilingan.
- Maikling buhayAng isang access token ay nagwawakas pagkalipas ng panahong sinusukat sa minuto; ang haba ay isang setting ng deployment at tatlumpung minuto kapag hindi itinakda.
- Pag-refresh at pag-ikotAng isang sesyon ay pinahahaba sa pamamagitan ng refresh token, at bawat paghaba ay naglalabas ng bagong pares. Kung ang isang nagamit nang refresh token ay iprisenta sa ikalawang pagkakataon, babawiin ang lahat ng sesyon ng taong iyon.
- Hindi nakabaon sa token ang mga pahintulotAng token ay may dalang pagkakakilanlan lamang; kung ano ang maaaring makita ng isang tao ay itinatanong sa database sa bawat kahilingan. Kaya ang isang pahintulot na binawi ay huminto na sa paggana bago pa mag-expire ang token na hawak.
- Susi ng integratorAng isang nakarehistrong aplikasyon ay kumokonekta gamit ang sarili nitong susi. Ang malinaw na halaga ay ipinapakita nang isang beses lamang, sa paglikha; ang iniimbak ay ang digest nito at ang hindi-lihim na unlapi na nagpapakilala sa isang susi.
- Ang organisasyon ang nagbibigay ng aksesGaano man kalawak ang paggamit sa isang aplikasyon, kung walang pahintulot na naitala ng organisasyon ay wala itong makikitang kahit isang talaan. Ang pahintulot ay may petsa, may saklaw at maaaring bawiin.
Pagbebersyon
- Nasa landas ang bersyonAng mga endpoint ay inilalathala sa likod ng unlaping bersyon; ang ibabaw ngayon ay bersyon uno.
- Ang pagbabagong nakasisira ay nagbubukas ng bagong landasHindi sinisira sa kinalalagyan ang kontrata ng umiiral na endpoint. Ang hindi magkatugmang pagbabago ay inilalathala sa bagong landas ng bersyon habang patuloy na gumagana ang luma.
- Sinasabi ng dokumento ang sarili nitong bersyonDala ng sanggunian ang numero ng bersyong pinagmulan nito; kung aling bersyon ang binabasa ninyo ay sinasagot mismo ng dokumento.
Mga kapaligiran at hangganan
Dalawang kapaligiran ang idineklara ng sanggunian: produksyon at lokal na pagbuo. Ang ugat na address ay ibinibigay sa isang integrator kasama ng kanyang susi; hindi ito inilalathala sa pahinang ito.
- Hiwalay na sinusukat ang liveness at readinessSinasabi ng isang endpoint na gumagana ang proseso; ang ikalawa ay nagpapadala ng tunay na query sa database at kinukumpirmang naaabot ito. Ang ikalawa lamang ang nagpapasya kung dapat bang magpadala ng trapiko.
- Nakalista ang pinapayagang pinagmulan sa browserAng mga cross-origin na kahilingan ay tinatanggap lamang mula sa mga pinagmulang idineklara nang maaga; habang walang laman ang listahan, tinatanggihan ang cross-origin na kahilingan ng browser.
- Hangganan ng katawanHindi maaaring lumampas sa limang megabyte ang katawan ng kahilingan. Ang malalaking pangkat ay naglalakbay bilang bulk transfer job na may sariling talaan ng katayuan, hindi bilang isang kahilingan.
- Hindi isinusulat sa log ang mga lihimWalang itinatagong authorization header, cookie, password o pambansang numero ng pagkakakilanlan ang log ng server.
Hangganan ng bilis
Ang hangganan ay bawat address at bawat minuto. Ang default ay 120 kahilingan bawat minuto at itinatakda sa deployment. Ang natitira ay iniuulat sa mga header ng bawat tugon.
| Header ng tugon | Ang sinasabi nito |
|---|---|
| x-ratelimit-limit | Ang kabuuang alawans sa loob ng yugto. |
| x-ratelimit-remaining | Kung ano ang natitira sa yugtong ito. |
| x-ratelimit-reset | Mga segundo hanggang mapanibago ang alawans. |
| retry-after | Ilang segundo bago muling subukan. Naroroon lamang sa tugong tumanggi sa kahilingan. |
Kapag nalampasan na ang hangganan, tinatanggihan ang kahilingan at sinasabi ng tugon kung ilang segundo maghihintay. Ang muling pagsubok ay ginagawa pagkatapos ng panahong iyon, hindi kaagad.
Pormat ng error
Ang bawat error ay bumabalik sa iisang sobre: isang maikling field ng kodigo na pagbabatayan ng makina, at isang field ng paliwanag na mababasa ng tao.
- errorAng maikling kodigo na pinagpapasyahan ng kliyente.
- messageAng paliwanag ng nangyari.
| Katayuan | Field ng kodigo | Ang ibig sabihin |
|---|---|---|
| 400 | Bad Request | Hindi tumutugma ang kahilingan sa schema. Pinangangalanan ng paliwanag ang field na kulang o hindi tama. |
| 401 | unauthenticated | Walang wastong pagkakakilanlan: walang ipinadalang token, nag-expire na ito, o hindi ito napatunayan. |
| 404 | Not Found | Walang ganoong endpoint, o walang ganoong talaan. |
| 429 | Too Many Requests | Nalampasan ang hangganan ng bilis; sinasabi ng tugon kung gaano katagal maghihintay. |
| 5xx | internal_error | Isang hindi inaasahang pagkabigo. Hindi ibinibigay ang detalye sa kliyente; isinusulat ito sa log ng server. |
Paghahati sa pahina
Ang mga endpoint na nagbabalik ng listahan ay tumatanggap ng parehong dalawang parametro at nagbabalik ng parehong pambilang, kaya hindi na muling isinusulat ang kliyente para sa bawat endpoint.
- limitIlang talaan ang dapat taglayin ng isang pahina. Isa ang pinakamababa, dalawang daan ang pinakamataas; limampu kapag hindi itinakda.
- offsetIlang talaan ang lalaktawan. Nagsisimula sa sero.
- totalIlang talaan sa kabuuan ang tumutugma sa mga salaan.
- countIlang talaan ang aktwal na dala ng tugong ito.
Inuulit din ng tugon ang limit at offset na ginamit nito; binabasa ng kliyente ang posisyon nito mula sa sagot sa halip na hulaan.
Palitan ng datos at mga webhook
Ang kaparaanan ng palitan ay isang setting, hindi hiwalay na produkto: dala ng bawat nakarehistrong aplikasyon sa sarili nitong talaan ang kaparaanang ginagamit nito.
| Kaparaanan | Ang ibig sabihin |
|---|---|
| Isang direksyon — palabas | Naglalathala ng datos ang Optifora; binabasa ito ng kabilang panig o nagpapasakop ito sa mga kaganapan. |
| Isang direksyon — papasok | Itinutulak ng kabilang panig ang datos; sinusuri ito ng Optifora at isinusulat. |
| Dalawang direksyon | Nagsusulat ang dalawang panig; ang tuntunin sa salungatan ay tinutukoy nang maaga. |
| Pagkakamayan | Ang bawat paglilipat ay nagbubukas ng sesyon: alok, pagpapatunay, pag-apruba, paglilipat at resibo. Ang resibo ay nananatili sa magkabilang panig. |
- Itinutulak palabas ang mga kaganapanIpinapadala ng webhook ang kaganapan sa address ng callback na idineklara ng nakarehistrong aplikasyon. Ang kaganapang hindi naihatid ay nananatili sa pila at muling sinusubukan; hindi ito basta iniiwan.
- Hindi nagsusulat nang dalawang beses ang parehong kahilinganAng kahilingang nagsusulat ay may dalang susi ng idempotency. Ang ikalawang kahilingan na may parehong susi ay hindi lumilikha ng ikalawang talaan.
- Sinusukat ang bawat tawagSino ang tumawag, kailan, anong saklaw at anong naging resulta — lahat ito ay naitatala. Ang parehong talaan ang sumasagot sa pag-debug at sa tanong kung sino ang humila ng datos na ito.
- Iisang pinto ang ginagamit ng sarili naming mga aplikasyonWalang pribilehiyadong ikalawang landas. Ang sarili naming integrasyon ang patunay ng ibabaw na hinaharap ng panlabas na developer.
Nakalatag na ang modelo ng datos para sa patong ng palitan; hindi pa inilalathala ang mga endpoint nito. Kapag nailathala na, iuugnay ng bahaging ito ang mga tala nila sa sanggunian.
Mga dokumentong sanggunian
Hindi kamay ang sumusulat ng sanggunian; nabubuo ito mula sa mga schema ng endpoint. Habang isinusuko ng bawat endpoint ang schema nito ay kusang napupuno ang dokumento, kaya hindi maaaring maghiwalay ang dokumento at ang aktwal na kilos.
- Ngayon: inihahandaModyul-modyul na inililipat ang mga schema. Bago ilathala ang dokumento, makikita rito ang kahilingan at tugon ng bawat endpoint.
- Dalawang pormat ang ilalathalaIsang dokumentong OpenAPI na nababasa ng makina, at isang pahinang sanggunian na hinango sa dokumento ring iyon at mababasa sa browser.
- May antas ang aksesBukas sa lahat ang pangkalahatang paglalarawan. Ang buong sanggunian ay maaaring nasa likod ng isang token ng dokumentasyon na ibinibigay sa nakarehistrong integrator; ang mga susi sa produksyon at ang mga address ng callback ay hindi usapin ng dokumentasyon — pag-aari sila ng talaan ng aplikasyon.
- Pamantayan ng addressDalawang sanggunian ang inilalathala at nakatakda ang kanilang mga address: bukas ang client-api.optifora.com/docs, samantalang ang admin-api.optifora.com/docs ay nangangailangan ng awtorisasyon at sarado sa labas. Wala pa sa alin man sa dalawa ang buhay ngayon; idaragdag ang mga link sa bahaging ito kapag buhay na.
Kung malinaw na ang inyong plano sa integrasyon, sumulat sa amin mula sa pahina ng kontak: kayo ang mauunang mabalitaan kapag nabuksan na ang ibabaw.
May tiyak ba kayong kahilingan?
Ipinaliliwanag ng mga pahinang ito kung paano gumagana ang proseso ng suporta. Kung may kahilingan o tanong kayo, sumulat sa amin mula sa pahina ng kontak.
Pumunta sa pahina ng kontak