RESTful žiniatinklio paslaugos

OSP RESTful žiniatinklio paslauga suteikia programinę prieigą prie Rodiklių duomenų bazės statistinių duomenų ir struktūrinių metaduomenų. Žiniatinklio paslauga konstruojama remiantis SDMX 2.1 RESTful žiniatinklio paslaugų specifikacija.

Žiniatinklio paslauga turi 2 veikimo režimus:

  • duomenų ištraukimas: kai žinomi duomenys, kuriuos norima paimti
  • struktūrinių metaduomenų ištraukimas: kai norima sužinoti žiniatinklio paslaugos duomenų tarnybinius (aprašomuosius) duomenis, reikalingus užklausai sukonstruoti ar duomenims interpretuoti

Žiniatinklio paslauga užklausos atsakymą gali grąžinti 2 formatais:

  • XML formatu, skirtu keistis SDMX struktūrizuotais duomenimis ir metaduomenimis
  • JSON formatu, skirtu duomenims pateikti ir vizualizuoti interneto puslapiuose

Visų SDMX užklausos atsakymo pranešimų struktūra yra tokia pati, t.y.:

  • antraštė
  • turinys (0..1)
  • poraštė (0..1)

Antraštėje pateikiami pranešimo tarnybiniai duomenys. Turinys priklauso nuo užklausos tipo ir formato. Poraštėje, pateikiamos duomenų užklausos apdorojimo klaidos, jei tokių buvo.

Duomenų ištraukimas

Visi Rodiklių duomenų bazėje saugomi duomenys gali būti gaunami naudojant žemiau pateiktą užklausos eilutę:

protocol://ws-entry-point/resource/flowRef/key/providerRef?queryStringParameters

Kur:

  • protocol – Žiniatinklio paslauga teikiama per https.
  • ws-entry-point – Žiniatinklio paslauga pasiekiama adresu 
    https://osp-rs.stat.gov.lt/rest_xml/ arba https://osp-rs.stat.gov.lt/rest_json/
  • resource – Duomenų užklausos išteklius yra data
  • flowRef - Duomenų srauto nuoroda, apibudinanti duomenis, kuriuos reikia grąžinti. Nuorodos formatas: <AGENCY_ID>, <FLOW_ID>, <VERSION> arba <AGENCY_ID>, <FLOW_ID> arba <FLOW_ID>, kur  AGENCY_ID – agentūros, kuri palaiko duomenų srautą, identifikatorius, FLOW_ID – duomenų srauto identifikatorius, VERSION – duomenų srauto versija
  • Key –  Grąžinamos serijos raktas, leidžiantis vienareikšmiškai nustatyti statistinius duomenis. Šioje paslaugos versijoje kelio parametras yra nepalaikomas.
  • providerRef – Duomenų teikėjas. Šioje paslaugos versijoje kelio parametras yra nepalaikomas.
  • queryStringParameters – šioje paslaugos versijoje palaikomi tik startPeriod ir endPeriod. Palaikomi datų formatai:

- YYYY – metiniams duomenims, pvz., 2017
- YYYY-S[1-2] – pusmečio duomenims, pvz., 2017-S1
- YYYY-Q[1-4] – ketvirčio duomenims, pvz, 2017-Q1
- YYYY-MM – mėnesiniams duomenims, pvz., 2017-01
- YYYY-W[01-52] – savaitiniams duomenims, pvz., 2017-W01
- YYYY-MM-DD - dieniniams duomenims, pvz., 2017-01-01

Pavyzdžiai:

Struktūrinių metaduomenų ištraukimas

Visi struktūriniai metaduomenys gali būti gaunami naudojant žemiau pateiktą užklausos eilutę:

protocol://ws-entry-point/resource/agencyID/resourceID/version/itemID?queryStringParameters

Kur:

  • protocol - Žiniatinklio paslauga teikiama per https.
  • ws-entry-point  - Žiniatinklio paslauga pasiekiama adresu https://osp-rs.stat.gov.lt/rest_xml/
  • resource - Grąžintinų struktūrinių metaduomenų tipas: dataflow arba datastructure
  • agencyID - Agentūros, palaikančios artefaktą, identifikatorius
  • resourceID - Artefakto identifikatorius
  • version - Grąžintino artefakto versija. Šioje paslaugos versijoje reikšmė visuomet vėliausia (latest)
  • queryStringParameters - Šioje paslaugos versijoje neprivalomi parametrai nepalaikomi

Pavyzdžiai:

Apribojimai

Žemiau yra išvardyti OSP RESTful žiniatinklio paslaugų apribojimai:

  • palaikomos anoniminės užklausos, nėra naudotojų autentifikacijos
  • duomenų užklausos atsakymo dydis ribojamas 1 000 000 stebėjimų įrašų.
  • didžiausias užklausos URL ilgis – 1000 simbolių
  • palaikomas tik bendrasis (angl. Generic) XML pranešimo formatas
  • palaikomas tik „plokščias“ duomenų vaizdas (parametras dimensionAtObservation = AllDimensions), nepalaikomas duomenų grupavimas (serijos ir grupės)
  • nepalaikomas versijavimas: visada grąžinama paskutinė duomenų versija
  • duomenų suspaudimas palaikomas naudojant HTTP Header lauką Accept-Encoding=gzip
  • nepalaikomi neprivalomi duomenų užklausos kelio parametrai key (=all) ir providerRef (=all)
  • nepalaikomi neprivalomi duomenų užklausos eilutės parametrai updatedAfter, firstNObservations, lastNObservations, dimensionAtObservation (=AllDimensions), detail (=full), includeHistory (=falsel)
  • nepalaikomi neprivalomi struktūrinių metaduomenų užklausos eilutės parametrai detail (=full), references (=parentsandsiblings)

Pastaba: Atkreipiame dėmesį, kad ateityje vystant žiniatinklio paslaugą pagal SDMX standartą, apribojimų sąrašas bus atnaujintas, kad atitiktų naujas funkcijas.