Jinsi API ya Optifora inavyofanya kazi
Ukurasa huu unaeleza umbo la API: jinsi utambulisho unavyothibitishwa, jinsi matoleo yanavyosonga mbele, mipaka ambayo ombi hukaa ndani yake, hitilafu inavyoonekana, na jinsi data inavyobadilishwa na ulimwengu wa nje.
Bidhaa bado inaendelezwa na uso wa API bado unakamilishwa. Hati ya marejeleo ya ncha zake itachapishwa kando; ukurasa huu hauna anwani wala mfano wa wito, bali mfumo wa kazi pekee.
Uthibitishaji wa utambulisho
Kila ombi ni la mtu au la programu iliyosajiliwa. Ombi lisilo na utambulisho linalofika kwenye ncha iliyolindwa hurudi likiwa halijathibitishwa.
- Tokeni ya BearerTokeni ya ufikiaji husafiri ndani ya kichwa cha idhini cha ombi. Imetiwa saini, na inaeleza tu ombi ni la nani.
- Umri mfupiTokeni ya ufikiaji huisha muda baada ya kipindi kinachopimwa kwa dakika; urefu wake ni mpangilio wa usimikaji na kwa kawaida ni dakika thelathini.
- Kuhuisha na kuzungushaKipindi cha matumizi huongezwa kwa tokeni ya kuhuisha, na kila uhuishaji hutoa jozi mpya. Iwapo tokeni ya kuhuisha iliyokwisha kutumika itawasilishwa mara ya pili, vipindi vyote vya mtu huyo hubatilishwa.
- Ruhusa hazijafungwa ndani ya tokeniTokeni hubeba utambulisho pekee; kile ambacho mtu anaruhusiwa kuona huulizwa kwenye hifadhidata katika kila ombi. Kwa hiyo ruhusa iliyoondolewa huacha kufanya kazi kabla tokeni iliyo mkononi haijaisha muda.
- Ufunguo wa mwunganishajiProgramu iliyosajiliwa huunganisha kwa ufunguo wake yenyewe. Thamani halisi huonyeshwa mara moja tu, wakati wa kuundwa; kinachohifadhiwa ni muhtasari wake wa kikriptografia pamoja na kianzio kisicho siri kinachowezesha ufunguo kutambulika.
- Taasisi ndiyo hutoa ufikiajiHaijalishi programu inatumika kwa upana kiasi gani, bila idhini iliyorekodiwa na taasisi haioni hata safu moja. Idhini huwa na tarehe, ina upeo wake na inaweza kubatilishwa.
Usimamizi wa matoleo
- Toleo hukaa ndani ya njiaNcha huchapishwa nyuma ya kianzio cha toleo; uso wa leo ni toleo la kwanza.
- Mabadiliko yanayovunja mkataba hufungua njia mpyaMkataba wa ncha iliyopo hauvunjwi pale ilipo. Mabadiliko yasiyoendana huchapishwa katika njia ya toleo jipya huku la zamani likiendelea kufanya kazi.
- Hati hueleza toleo lake yenyeweMarejeleo hubeba namba ya toleo yaliyotolewa kutoka kwake; toleo unalosoma hujibiwa na hati yenyewe.
Mazingira na mipaka
Marejeleo hutangaza mazingira mawili: uzalishaji na uendelezaji wa ndani. Anwani ya mzizi hukabidhiwa kwa mwunganishaji pamoja na ufunguo wake; haichapishwi katika ukurasa huu.
- Uhai na utayari hupimwa kila kimoja peke yakeNcha moja hueleza kuwa mchakato unafanya kazi; ya pili hutuma hoja halisi kwenye hifadhidata na kuthibitisha inafikika. Ni ya pili pekee inayoamua kama trafiki ipelekwe.
- Asili za kivinjari zimebanwa kwa orodhaMaombi kutoka asili tofauti hukubaliwa tu kutoka asili zilizotangazwa mapema; wakati orodha ikiwa tupu, ombi la kivinjari kutoka asili tofauti hukataliwa.
- Kikomo cha mwili wa ombiMwili wa ombi hauwezi kuzidi megabaiti tano. Seti kubwa husafiri kama kazi ya uhamisho wa wingi yenye rekodi yake ya hali, si kama ombi moja.
- Siri haziandikwi katika kumbukumbuKumbukumbu za seva hazihifadhi kichwa cha idhini, wala kidakuzi, wala nenosiri, wala namba ya kitambulisho cha taifa.
Kikomo cha maombi
Kikomo ni kwa kila anwani na kwa kila dakika. Kiwango cha kawaida ni maombi 120 kwa dakika na huwekwa wakati wa usimikaji. Kilichobaki huelezwa katika vichwa vya kila jibu.
| Kichwa cha jibu | Kinachoeleza |
|---|---|
| x-ratelimit-limit | Jumla ya kiasi kinachoruhusiwa ndani ya dirisha. |
| x-ratelimit-remaining | Kilichobaki katika dirisha hili. |
| x-ratelimit-reset | Sekunde zilizosalia hadi kiasi kinachoruhusiwa kihuishwe. |
| retry-after | Sekunde ngapi kabla ya kujaribu tena. Hupatikana tu katika jibu lililokataa ombi. |
Kikomo kikishavukwa ombi hukataliwa na jibu hueleza muda wa kusubiri, kwa sekunde. Jaribio jipya hufanywa baada ya muda huo, si mara moja.
Muundo wa hitilafu
Kila hitilafu hurudi katika bahasha ile ile: sehemu ya msimbo mfupi ili mashine iamue njia, na sehemu ya maelezo ili mtu aisome.
- errorMsimbo mfupi ambao mteja huutumia kuamua njia.
- messageMaelezo ya kilichotokea.
| Hali | Sehemu ya msimbo | Maana yake |
|---|---|---|
| 400 | Bad Request | Ombi halilingani na skima. Maelezo hutaja sehemu iliyokosekana au isiyo sahihi. |
| 401 | unauthenticated | Hakuna utambulisho halali: hakuna tokeni iliyotumwa, imeisha muda, au haikuthibitika. |
| 404 | Not Found | Hakuna ncha kama hiyo, au hakuna rekodi kama hiyo. |
| 429 | Too Many Requests | Kikomo cha maombi kimezidishwa; jibu hueleza muda wa kusubiri. |
| 5xx | internal_error | Hitilafu isiyotarajiwa. Maelezo yake hayakabidhiwi kwa mteja; huandikwa katika kumbukumbu za seva. |
Mgawanyo wa kurasa
Ncha zinazorejesha orodha huchukua vigezo viwili vile vile na hurejesha vihesabu vile vile, hivyo mteja anayeshughulikia kurasa haandikwi upya kwa kila ncha.
- limitRekodi ngapi ukurasa unapaswa kubeba. Angalau moja, kiwango cha juu mia mbili; hamsini isipowekwa.
- offsetRekodi ngapi za kurukwa. Huanza sifuri.
- totalRekodi ngapi kwa jumla zinazolingana na vichujio.
- countRekodi ngapi jibu hili linabeba kihalisi.
Jibu pia hurejesha kikomo na nafasi ya kuanzia iliyotumika; mteja husoma nafasi yake kutoka jibu badala ya kuikisia.
Kubadilishana data na webhook
Namna ya kubadilishana ni mpangilio, si bidhaa tofauti: kila programu iliyosajiliwa hubeba namna inayofanyia kazi katika rekodi yake yenyewe.
| Namna | Maana yake |
|---|---|
| Njia moja — kwenda nje | Optifora huchapisha data; upande mwingine huisoma au hujiandikisha kupokea matukio. |
| Njia moja — kuingia ndani | Upande mwingine husukuma data; Optifora huihakiki kisha huiandika. |
| Njia mbili | Pande zote mbili huandika; kanuni ya kutatua mgongano huwekwa mapema. |
| Kupeana mkono | Kila uhamisho hufungua kipindi: pendekezo, uhakiki, idhini, uhamisho na risiti. Risiti hubaki kwa pande zote mbili. |
- Matukio husukumwa njeWebhook hutuma tukio kwenye anwani ya kurudisha wito iliyotangazwa na programu iliyosajiliwa. Tukio lisiloweza kufikishwa hubaki kwenye foleni na hujaribiwa tena; halitupwi kimya kimya kamwe.
- Ombi lile lile haliandiki mara mbiliOmbi la kuandika hubeba ufunguo wa kuzuia kurudia. Ombi la pili lenye ufunguo ule ule haliundi rekodi ya pili.
- Kila wito hupimwaNani aliita, lini, kwa upeo upi na kwa matokeo gani — yote hurekodiwa. Rekodi hiyo hiyo hujibu utatuzi wa hitilafu na pia swali la nani alivuta data hii.
- Programu zetu wenyewe hutumia mlango ule uleHakuna njia ya pili yenye upendeleo. Muunganisho wetu wenyewe ni uthibitisho wa uso anaoukuta msanidi wa nje.
Muundo wa data wa tabaka la kubadilishana upo tayari; ncha zake bado hazijachapishwa. Zitakapochapishwa, sehemu hii itaunganisha na maingizo yake katika marejeleo.
Hati za marejeleo
Marejeleo hayaandikwi kwa mkono; hutolewa kutoka skima za ncha. Kila ncha inapokabidhi skima yake hati hujijaza yenyewe, hivyo hati na tabia halisi haziwezi kutofautiana.
- Leo: inaandaliwaSkima zinasonga moduli kwa moduli. Kabla hati haijachapishwa, ombi na jibu la kila ncha vitaonekana ndani yake.
- Miundo miwili itachapishwaHati ya OpenAPI inayosomeka na mashine, na ukurasa wa marejeleo unaotolewa kutoka hati hiyo hiyo na kuvinjariwa katika kivinjari.
- Ufikiaji una madarajaMuhtasari uko wazi kwa kila mtu. Marejeleo kamili yanaweza kukaa nyuma ya tokeni ya nyaraka inayotolewa kwa mwunganishaji aliyesajiliwa; funguo za uzalishaji na anwani za kurudisha wito si suala la nyaraka hata kidogo — ni mali ya rekodi ya programu.
- Kiwango cha anwaniMarejeleo mawili huchapishwa na anwani zake ni thabiti: client-api.optifora.com/docs iko wazi, admin-api.optifora.com/docs inahitaji idhini na imefungwa kwa nje. Hakuna hata moja iliyo hai leo; viungo vitaongezwa katika sehemu hii mara vitakapokuwa hai.
Iwapo mpango wako wa muunganisho tayari uko wazi, tuandikie kupitia ukurasa wa mawasiliano: utakuwa miongoni mwa wa kwanza kuarifiwa uso utakapofunguliwa.
Je, una ombi maalum?
Kurasa hizi zinaeleza jinsi mchakato wa msaada unavyofanya kazi. Ukiwa na ombi au swali, tuandikie kutoka ukurasa wa mawasiliano.
Nenda kwenye ukurasa wa mawasiliano