Haku- ja vastaussanomat

Hakusanoma

Hakusanoma lähetään Kanta-palveluihin HTTP POST-pyyntönä (request). Toimintakykytiedon resurssin uusin versio haetaan search-interaktiolla: POST [base]/[resource-type]/_search. Toimintakykytiedon resurssin kaikki versiot haetaan history-interaktiolla: POST [base]/[resource-type]/_history.

Potilastietovarannon hauissa käytetään search- ja history-interaktioita. History-interaktiota on sallittua käyttää vain haettaessa toimintakykytietoja rekisterinpitäjän omasta rekisteristä. Sosiaalihuollon asiakastietovarannon hauissa käytetään vain search-interaktiota, sillä asiakastietojärjestelmästä on mahdollista hakea vain resurssin viimeisin, voimassa oleva versio. Sosiaalihuollon asiakastietovaranto ei palauta haussa asiakastietojärjestelmälle resurssin aiempia versioita tai mitätöityjä resursseja. Sosiaalihuollossa resurssin aiempi versio tai mitätöity resurssi voidaan hakea Sosiaalihuollon asiakastietovarannon arkistonhoitajan käyttöliittymästä.

Pyynnön URL:in muoto noudattaa FHIR määrittelyjä (Style Guide). Eri ympäristöjen käytettävät juuret ilmoitetaan palveluun liittyville tietojärjestelmätoimittajille erikseen eikä niitä julkisteta tässä soveltamisoppaassa.

Haussa käytettäviä hakuparametreja ei saa lisätä pyynnön URLiin, koska URLin osana hakuparametrien arvot, kuten asiakkaan yksilöivä tunnus, voivat jäädä esimerkiksi verkkolaitteiden lokitietoihin.

HTTP-pyynnön header

Haun HTTP-pyynnön header-osuus noudattaa Kanta-palveluiden yhteisiä Kanta FHIR HTTP header -dokumentin mukaisen HTTP-headerin ja JSON Web Tokenin määrittelyitä. Potilastietovarantoon lähetettävän HTTP-pyynnön (request) tiedot ja niiden pakollisuudet on määritelty dokumentin Kanta FHIR HTTP-header taulukon 2.1 Kanta-palveluiden HTTP pyynnön header kentät sarakkeessa PTA ja Sosiaalihuollon asiakastietovarantoon lähetettävän HTTP-pyynnön sarakkeessa SHA. JSON Web Tokenin tiedot ja niiden pakollisuudet on määritelty dokumentin Kanta JSON Web Token taulukossa 4.1 Kanta-palveluiden JWT Claimit. Potilastietovarantoon lähetettävän JWT:n tiedot ja tietojen pakollisuudet on määritelty sarakkeessa PTA ja Sosiaalihuollon asiakastietovarantoon lähetettävän JWT:n sarakkeessa SHA.

HTTP-pyynnön body

Toimintakykytiedon haussa käytettävät hakuparametrit lähetetään HTTP-pyynnön body-osuudessa. Sosiaalihuollon asiakastietovarannon tukemat hakuparametrit on kuvattu taulukossa 1. Asiakastietovaranto tukee hakuparametreina sekä toimintakykytiedon tietosisällössä olevia tietoja että Provenance-resurssissa olevia toimintakykytiedon metatietoja. Hakuparametrit ovat joko ehdollisesti pakollisia (eP) tai vapaaehtoisia (O). Hakuparametrien FHIR-hakuparametrit ja hakuparametrien tyypit tarkennetaan syksyllä 2025.

Potilastietovarannon tukemat hakuparametrit tarkennetaan syksyllä 2025.

Taulukko 1. Sosiaalihuollon asiakastietovarannossa käytettävät hakuparametrit

Esimerkkejä hakuparametrien käytöstä

Yhteen hakuun voidaan liittää useita hakuparametreja, alla esimerkkejä hakulauseista.

Asiakkaan kaikkien merkintöjen toimintakyvystä ja toimintakykyarvioiden haku asiakkaan tunnisteen perusteella

POST [base]/Observation/_search

Content-Type: application/x-www-form-urlencoded

patient:identifier={system|value}

Esim. patient:identifier=urn:oid:1.2.246.21|300111A9001

Yksittäisen merkinnän toimintakyvystä/toimintakykyarvion haku asiakkaan ja resurssin tunnisteen perusteella

POST [base]/Observation/_search

Content-Type: application/x-www-form-urlencoded

patient:identifier={system|value}&identifier={system|value}

Vastaussanoma

Kanta-palvelut palauttaa vastauksena HTTP-vastauksen (response), jossa tiedot palautetaan HTTP header- ja body-osuuksiin jaettuna.

HTTP-vastauksen header

HTTP-vastauksen header-osuus noudattaa Kanta-palvelujen yhteistä Kanta FHIR HTTP header määrittelyä. Potilastietovarannon palauttaman HTTP-vastauksen tiedot ja niiden pakollisuudet on määritelty dokumentin Kanta FHIR HTTP-header taulukon 3.1 Kanta-palveluiden HTTP pyynnön header kentät sarakkeessa PTA ja Sosiaalihuollon asiakastietovarannon palauttaman HTTP-vastauksen sarakkeessa SHA.

HTTP-vastauksen body

Onnistuneessa haussa Kanta-palvelut palauttaa HTTP-statuskoodin 200 OK ja vastauksen HTTP-bodyssa Bundle-resurssi-instanssin, jonka tyyppi (type) on searchset. Palautettujen hakutulosten määrä ilmoitetaan Bundlen total-elementissä. Merkinnän toimintakyvystä ja toimintakykyarvioiden tiedot palautetaan Observation-resursseissa ja niihin liittyvät metatiedot Provenance-resursseissa, jotka ovat Bundlen entry-elementin sisällä.

Alla on esimerkki Bundle resurssi-instanssista, jonka sisällä palautetaan kaksi Observation-resurssia ja niiden metatiedot Provenance-resursseilla.

Esimerkki Kanta-palvelujen palauttamasta vastaussanomasta onnistuneessa haussa

{
    "resourceType": "Bundle",
    "id": "92685db0-1b58-4cea-b1fa-289e8ab58811",
    "type": "searchset",
    "total": 2,
    "entry": [
        {
            "resource": {
                "resourceType": "Observation",
                ...
            }
        },
        {
            "resource": {
                "resourceType": "Provenance",
                ...
            }
        }, 
        {
            "resource": {
                "resourceType": "Observation",
                ...
            }
        },
        {
            "resource": {
                "resourceType": "Provenance",
                ...
            }
        } 
    ]
}

Jos Kanta-palvelut on suorittanut haun onnistuneesti, mutta haku ei tuota hakutuloksia, Kanta-palvelut palauttaa HTTP-statuskoodin 200 OK ja Bundle-resurssin, jossa hakutulosten määrä (total) on 0. Alla on esimerkki Bundle-resurssista, joka ei palauta hakutuloksia.

Esimerkki Kanta-palvelujen palauttamasta vastaussanomasta onnistuneessa haussa, joka ei tuota hakutuloksia

{
    "resourceType": "Bundle",
    "id": "073ce2b1-4c39-4cae-a479-ca59c8f74fef",
    "type": "searchset",
    "total": 0,
}

Vastaussanoma virhetilanteessa

Virhetilanteessa Kanta-palvelut palauttaa Bundle-resurssin entry-elementissä HTTP-virhestatuskoodin ja OperationOutcome-resurssin, jolla ilmoitetaan tarkempi virhe.

Kanta-palvelujen palauttaman OperationOutcome-resurssin tiedot on kuvattu sivun Tallennus- ja vastaussanomat luvussa Vastaussanoma virhetilanteessa.