Siekiant užtikrinti prieinamumą ir vienodą greitaveiką visiems Rivile API v2 klientams bei siekiant apsaugoti platformą nuo kenkėjiškų atakų, visoms užklausoms yra taikomi apribojimai. Šie apribojimai nustato, kiek užklausų gali siųsti vienas paslaugos naudotojas per tam tikrą laiką. Viršijus nurodytus apribojimus užklausos automatiškai blokuojamos.
Naudotojas identifikuojamas naudojant vieną iš identifikatorių: API raktą, vartotojo vardą arba IP adresą. Šioje lentelėje pateikiami API užklausų apribojimai pagal identifikatoriaus tipą.
| Naudotojo identifikatorius | Nominalus apribojimas | Pikinis apribojimas |
|---|---|---|
| API raktas | 10 užklausų per sekundę | 30 užklausų per sekundę |
| Vartotojo vardas | 10 užklausų per sekundę | 30 užklausų per sekundę |
| IP adresas | 10 užklausų per sekundę | 30 užklausų per sekundę |
Kai į Rivile API v2 siunčiate užklausas, kuriose nėra nurodytas nei API raktas, nei prisijungusio vartotojo vardas, pavyzdžiui MSCAN arba MGAMA aplikacijos pirmame lange prieš prisijungimą, tokios užklausos ribojamos pagal IP adresą.
Kiekvienas IP adresas gali siųsti ne daugiau nei 10 užklausų per sekundę. Sekančios užklausos toje pačioje sekundėje yra blokuojamos.
Kai Rivile API v2 yra naudojamas prisijungus su vartotojo vardu, pavyzdžiui iš MSCAN arba MGAMA aplikacijos, užklausos yra ribojamos pagal vartotojo vardą.
Apribojimai taikomi kiekvienam vartotojui atskirai. Vieno vartotojo vardu galite siųsti ne daugiau nei 10 užklausų per sekundę. Sekančios užklausos toje pačioje sekundėje užklausos yra blokuojamos.
Įprastai, neturėtumėte pasiekti šių apribojimų.
Kai į Rivile API v2 siunčiate užklausas, kuriose yra nurodytas jūsų API raktas, tokios užlausos yra ribojamos pagal užklausoje nurodytą API raktą.
Apribojimai taikomi kiekvienam API raktui atskirai. Su vienu APi raktu galite siųsti ne daugiau nei 10 užklausų per sekundę. Tolesnės užklausos yra blokuojamos.
Kad neviršytumėte numatytų apribojimų, programuojant integracijas rekomenduojame laikytis API taikomų geriausių praktikų ir rekomendacijų.
Nurodyti užklausų apribojimai gali būti keičiami be atskiro perspėjimo. Taip pat, ypatingais atvejais, galite susidurti su kitokiais užklausų apribojimais.
Dėl šių priežasčių integracijų algoritmuose naudokite ne statinį, čia nurodytą užklausų skaičių, o specialias tam skirtas antraštes (angl. header).
| Antraštė | Aprašymas |
|---|---|
X-RateLimit-Remaining |
Kiek neblokuojamų API užklausų dar galima siųsti šią sekundę |
X-RateLimit-Replenish-Rate |
Kiek kreditų sekančią sekundę bus papildytas esamo naudotojo identifikatorius (API raktas, vartotojo vardas arba IP adresas) |
X-RateLimit-Burst-Capacity |
Kiek maksimaliai neblokuojamų API užklausų galima siųsti per sekundę |
X-RateLimit-Requested-Tokens |
Kiek kreditų bus sunaudota išsiuntus vieną API užklausą |
Šios antraštės gražinamos kiekviename Rivile API v2 atsakyme. Detalus techninis šių antraščių aprašymas pateikiamas žemiau.
Pasiekus nustatytą užklausų ribą Rivile API v2 gražins HTTP 429 klaidos kodą. Gavus atsakymą su šiuo klaidos kodu privalote iš karto stabdyti siunčiamas užklausas ir laukti bent vieną sekundę. Po sekundės naudotojo identifikatorius turėtų pasipildyti naujais kreditais ir apribojimas atsiblokuoti. Jeigu sekanti užklausa visgi taip pat gražina HTTP 429 klaidos pranešimą, eksponentiškai didinkite laukimo laiką ir taip kartokite ciklą kelis kartus.
Jeigu nesilaikysite šios taisyklės ir nekreipsite dėmesio į sistemos gražinamą HTTP 429 klaidos pranešimą, jūsų naudotojo identifikatorius gali būti blokuotas ilgesniam laikui.
Blokavimo režime užlausų skaičiavimas nesustoja, todėl gavus HTTP 429 klaidos kodą turite stabdyti siunčiamas užklausas.
API užklausų apribojimai veikia Token Bucket algoritmo principu. Kiekvienas naudotojo identifikatorius sistemoje turi specialią talpyklą, kuri per sekundę pasipildo numatytu užklausų kreditu (angl. replenish rate). Tiek pat jų galima ir išnaudoti. Tačiau iš viso kiekviena saugykla gali sukaupti šiek tiek didesnį užklausų kreditą, nei jis papildomas per sekundę (angl. burst rate). Tai įgalina trumpą laiką siųsti šiek daugiau užklausų, nei yra numatyta nominaliame režime.
Pavyzdžiui, jeigu naudotojo identifikatorius papildomas 10 užklausų kreditu, bet iš viso galima sukaupti iki 30 užklausų kreditą, reiškia, kad maksimaliai galite siųsti 30 užklausų per sekundę, jeigu prieš tris sekundes ar daugiau jau siuntėte 30 užklausų, o iki dabar jų visiškai nesiuntėte. Jeigu jau kurį laiką siuntėte iki 10 užklausų per sekundę, tuomet taip pat vieną kartą galite išsiųsti 30 užklausų per sekundę.
Pikinė apribojimo vertė yra skirta nenumatytiems atvejams, o ne nuolatiniam užklausų srautui.
Nežiūrint į didesnę leistiną užklausų per sekundę ribą (lentelėje viršuje - pikinis apribojimas), integracijose rekomenduojame orientuotis į nominalią ribą. Kiekvienos užklausos atsakyme įvertinkite duomenis nurodytus specialiose antraštėse ir siekite, kad X-RateLimit-Remaining reikšmė nebūtų mažesnė nei X-RateLimit-Burst-Capacity - X-RateLimit-Replenish-Rate - 1 reikšmių skirtumas. Prieš siunčiant kiekvieną užklausą papildomai įvertinkite X-RateLimit-Remaining - (X-RateLimit-Requested-Tokens * jūsų_norimas_siųsti_užklausų_kiekis) formulės rezultatą.
Visiems klientams taikomi vienodi užklausų apribojimai. Jie užtikrina Rivile API v2 platformos stabilumą ir greitaveiką visiems klientams, todėl išimtys nėra daromos.