Äriregistri REST API võimaldab lepingulistel partneritel teha masinloetavaid päringuid äriregistri andmete kohta. REST teenused on mõeldud infosüsteemidevaheliseks kasutamiseks olukorras, kus andmeid on vaja pärida reaalajas ja struktureeritud JSON formaadis.
REST API ametlik live dokumentatsioon asub aadressil https://ar-rest.rik.ee/docs. Sama aadressi tuleb kasutada teenuste tehniliste parameetrite, vastuste ja skeemide kontrollimiseks.
REST API teenuste kasutamiseks on üldjuhul vajalik sõlmida Registrite ja Infosüsteemide Keskusega leping ning kasutada lepingu alusel väljastatud API võtit. API võtit kasutatakse ligipääsutokeni saamiseks, millega tehakse järgnevad REST päringud.
Lepingu sõlmimine ja ligipääs
- REST API kasutamiseks tuleb sõlmida Registrite ja Infosüsteemide Keskusega leping, kui konkreetse teenuse juures ei ole märgitud teisiti.
- Lepingulisele partnerile võimaldatakse API võtme loomine ja kasutamine. Täpsem juhis api võtme loomiseks: API võtmete lisamine REST teenustele | Abiinfo
- API võtmega autentimise teenus tagastab ligipääsutokeni, mida kasutatakse järgnevates REST teenuste päringutes.
- Ligipääs ja nähtavad andmed sõltuvad teenusest, lepingu tingimustest ning kasutaja juurdepääsu alusest.
Autentimine
REST API kasutamisel toimub autentimine API võtme ja ligipääsutokeni alusel.
- Kasutaja kutsub välja API võtmega autentimise teenuse GET /keyLogin/.
- Autentimise vastus tagastab access_token väärtuse.
- Saadud ligipääsutoken lisatakse järgnevatele REST päringutele autentimiseks Bearer tokenina.
API võtmega autentimise teenuse kirjeldus: API võtmega autentimine | e-äriregistri avaandmed
Kui konkreetse teenuse juures on avalikus dokumentatsioonis märgitud teistsugune ligipääsureegel või teenus on ilma autentimiseta kasutatav, tuleb lähtuda vastava teenuse kirjeldusest live dokumentatsioonis.
API teenuste nõuded ja limiidid
| Nõue | Limiit |
|---|---|
| Maksimaalne päringute arv lepingupartneri kohta | 50 000 päringut päevas |
| Maksimaalne päringute arv ühe API võtme kohta | 50 000 päringut päevas |
Mahtude ületamisel võidakse piirata lepingupartneri või API võtme päringute tegemise õigust. Suurema päevase mahu vajaduse korral tuleb see eelnevalt RIKiga kooskõlastada.
REST API tehnilised põhimõtted
- REST API kasutab HTTP meetodeid, näiteks GET ja vajadusel POST, vastavalt konkreetse endpointi kirjeldusele.
- Päringu parameetrid antakse vastavalt teenuse kirjeldusele kas URL-i path parameetritena, query parameetritena, päistes või päringu kehas.
- Vastused tagastatakse JSON formaadis.
- Veaolukordades tagastatakse HTTP staatusekood ning veavastus vastavalt konkreetse teenuse skeemile.
- Teenuste sisendid, väljundid, kohustuslikud väljad ja võimalikud veavastused on kirjeldatud OpenAPI/Swagger dokumentatsioonis.
Teenuse aadressid ja dokumentatsioon
| Kirjeldus | Aadress |
|---|---|
| REST API live baasaadress | https://ar-rest.rik.ee/ |
| REST API live OpenAPI/Swagger dokumentatsioon | https://ar-rest.rik.ee/docs |
| OpenAPI JSON kirjeldus | https://ar-rest.rik.ee/openapi.json |
REST teenuste puhul tuleb lähtuda live dokumentatsioonist aadressil https://ar-rest.rik.ee/docs. Seal on iga endpointi meetod, aadress, parameetrid, vastuse skeemid ja võimalikud veavastused.
Andmete kasutamine
REST API kaudu saadud andmete kasutamisel tuleb lähtuda lepingu tingimustest, õigusaktidest ning konkreetse teenuse juurdepääsu reeglitest. Kui teenus tagastab piiratud juurdepääsuga andmeid, tuleb andmete kuvamisel ja edastamisel arvestada teenuse dokumentatsioonis kirjeldatud nähtavuse ulatusega.