Skip to content

20 Kiirjuhend

Jump to bottom
Andres Rattur edited this page Mar 4, 2026 · 2 revisions

API päringute limiidid

PISTRIKu võimaliku ülekoormamise ehk käideldavuse (availability - õigel ajal kättesaadav ja kasutuskõlblik) tagamiseks on PISTRIKus realiseeritud API päringute limiidid (API rate limit). PISTRIK piirab REST API päringute arvu, mida saab teha üks liidestuja kindla ajavahemiku jooksul. Piirang aitab vältida võimalikku teenuste kuritarvitamist ja teenustõkestusründeid ning tagada, et API oleks kättesaadav kõigile tarbijatele.

ToDo!: Sliding window (1 min, 5 min, 1h limiidid) lahti kirjutada

Esimene API päring (Quick start)

Järgmiste eelduste täitmisel saab teostada kõige lihtsama alloleva PISTRIKu süsteemi ülevaloleku kontrollipäringu, mis võimaldab veenduda seadistuste ja ligipääsude ning API võtme toimimises:

  1. X-tee liikmelisus – olete RIA-ga sõlminud x-tee liikmesuse lepingu
  2. X-tee turvaserverile ligipääs – olete x-tee turvaserveri teenusepakkujalt sisse ostnud (sh edastanud turvaserveri omanikule SIGN serdi) või olete oma turvaserveri paigaldanud/seadistanud (sh seadistanud AUTH ja SIGN serdid) ja Eesti x-tee ökosüsteemiga liidestanud
  3. X-tee alamsüsteem registreeritud ja seadistatud – olete x-tee iseteeniduskeskkonnas registreerinud ja RIA keskserverisse lisanud oma alamsüsteemi ja seadistanud selle oma/x-tee turvaserveri teenusepakkuja turvaserveris
  4. X-tee alamsüsteemile on antud ligipääs – /GOV/70008658/kotkas-pistrik alamsüsteemis teenuste tarbimise ligipääs on nimetatud teie alamsüsteemile. Ligipääsu saab kontrollida x-tee metadata allowedMethods päringuga (vt Lisamaterjalide lehele)
  5. Olete veendunud, et saate x-teel oma alamsüsteemi alt päringuid teha – st omate võrgu tasemel ligipääsu oma turvaserverini ja kahepoolse autentimisega krüpteeritud ühenduse (mTLS) loomine õnnestub kliendi ning turvaserveri vahel. Näiteks võib kontrollida PISTRIKu poolt avatud teenuseid x-tee metadata allowedMethods päringuga. Turvaserveri portide ülevaade on toodud turvaserveri paigaldusjuhendis.

GET system/status näidispäring otseliidestujana

curl --location --globoff '{{baseUrl}}/api/v1/system/status' \
--header 'X-Road-Client: {{xRoadInstance}}/{{clientMemberClass}}/{{clientMemberCode}}/{{clientSubsystemCode}}' \
--header 'X-Road-Id: {{randomUUID}}' \
--header 'Accept: application/json'

Näidisvastus otseliidestujana, kui süsteem töötab

HTTP 200
{
    "status": "OK"
}

GET system/status näidispäring liidestumisel platvormiteenusepakkuja kaudu

curl --location --globoff '{{baseUrl}}/api/v1/system/status' \
--header 'X-Road-Client: {{xRoadInstance}}/{{clientMemberClass}}/{{clientMemberCode}}/{{clientSubsystemCode}}' \
--header 'X-Road-Id: {{randomUUID}}' \
--header 'X-Road-Represented-Party: {{xRoadRepresentedParty}}' \
--header 'Accept: application/json'

Näidisvastus liidestumisel platvormiteenusepakkuja kaudu, kui süsteem töötab

HTTP 200
{
    "status": "OK"
}

Esimese päringu edukal teostamisel saab edasi liikuda PISTRIKu klassifikaatoreid ja aruandlusobjekte väljastavate päringute ning liidestuja konkreetsest vajadusest lähtuvalt vajalike teenuste saatekirjade ja käitlustoimingute CRUD teenuste kasutuselevõtmisele.

Kõigi päringute ühised andmeväljad

Järgnevalt on selgitatud PISTRIKu API x-tee päringute andmevälju, mis kohalduvad kõigile päringutele:

Päis Selgitus Näidis Kohustuslik
baseURL X-teel tarbitava PISTRIKu API baasaadress x-tee REST sõnumiprotokolli kohaselt. ee-test/GOV/70008658/kotkas-pistrik/xroadservice/ JAH
X-Road-Client PISTRIKu x-tee teenuste tarbija alamsüsteemi nimetus ee-test/GOV/70008658/pistrik-client JAH
X-Road-Represented-Party Platvormiteenuse pakkuja kliendi (ehk kelle andmeid PISTRIKusse edastatakse) äriregistrikood. Otseliidestuse korral ei ole kasutusel. 12345678 EI*
X-Road-Id Iga x-tee päringu globaalselt unikaalne ID, nt UUIDv4 0270c57d-0edb-4596-8b1d-60502b67857a JAH
X-Road-UserId X-tee päringu käivitanud kasutaja isikukood, mille ees on kahetäheline riigikood EE38001020304 EI
X-Road-Issue Tuvastab vastuvõetud taotluse, küsimuse või dokumendi, mis oli teenuse päringu põhjuseks. Seda välja võib kasutada kliendi infosüsteem, et ühendada teenuse päringud (ja vastused) töömenetlustega. XYZ taotlusega seotud päring EI
Authorization PISTRIKu iseteeninduskeskkonnas genereeritud API võti Bearer qfVhvXbC7vqa3VPnRWWqOqLbB5Oh0XQQd4WFBgrQ5HbCdRBGKxCN1aSvBKmcdbYMmWwR7bZBkI0oOXWdaeFWvg== JAH
*Platvormiteenuse pakkuja vahendusel liidestumise korral kohustuslik

baseUrl-i komponendid

Tulenevalt x-tee REST sõnumiprotokollist koosneb `baseUrl järgmistest osadest:

{{consumerSecurityServerUrl}}/{{restProtocolVersion}}/{{xRoadInstance}}/{{serviceMemberClass}}/{{serviceMemberCode}}/{{serviceSubsystemCode}}/{{serviceCode}}

X-tee protokolli spetsiifiliste HTTP päiste selgitusega on täiendavalt võimalik tutvuda x-tee REST sõnumiprotokollis.

Kõigi andmeid muutvate päringute ühised andmeväljad

Andmeid muutvates päringutes tuleb samaaegsete muudatustega andmete ülekirjutamise vältimiseks kaasa anda muudetava/kustutatava objekti versiooni ID If-Match

Päis Selgitus Näidis Kohustuslik
If-Match Muutmispäringuga edastatav kehtiva objekti versioon, et välistada teiste osapoolte saatekirja muudatuste mitte-nägemist või ülekirjutamist. Mittevastava versiooni puhul tagastatakse HTTP veakood 412. "1" JAH

Clone this wiki locally