Haun vastaus

Hakuoperaation HTTP vastaus (response)

HTTP vastauksen tiedot palautetaan HTTP header- ja body-osuuksiin jaettuna.

Vastauksen HTTP header

HTTP-vastauksen header-tiedot on kuvattu Kanta-palvelujen yhteisessä FHIR- ja REST-soveltamisoppaassa sivulla Kanta HTTP header-tiedot FHIR-rajapinnassa.

Vastauksen HTTP header esimerkki

Status code: 200
x-request-id: cfaafd43-9234-4501-8508-8d840fc374a0
expires: 0
cache-control: no-cache, no-store, max-age=0, must-revalidate
x-xss-protection: 0
pragma: no-cache
x-frame-options: DENY
date: Mon, 12 Aug 2024 07:31:10 GMT
vary: Origin, Access-Control-Request-Method, Access-Control-Request-Headers
x-content-type-options: nosniff
strict-transport-security: max-age=31536000 ; includeSubDomains
transfer-encoding: chunked
content-type: application/json

Vastauksen HTTP body

Onnistuneen hakuoperaation vastauksena palautuu Bundle resurssi-instanssi, joka on tyypiltään searchset (type). Bundle-resurssin tiedoissa palautetaan nykyisen haun tiedot sekä tarvittaessa jatkohaun tekemiseen tarvittavat tiedot. Bundle-resurssin entryn DocumentReference-resurssissa palautetaan kukin palautuva CDA R2 asiakirja metatietoineen.

Esimerkki Bundle resurssi-instanssista, jonka sisällä palautuu DocumentReference-resurssissa kaksi asiakirjaa metatietoineen:

{
    "resourceType": "Bundle",
    "id": "073ce2b1-4c39-4cae-a479-ca59c8f74fef",
    "meta": {"lastUpdated": "2024-04-11T15:07:09"},
    "type": "searchset",
    "entry": [
        {
            "resource": {
                "resourceType": "DocumentReference",
                ...
            }
        },
        {
            "resource": {
                "resourceType": "DocumentReference",
                ...
            }
        } 
    ]
}

DocumentReference -rakenne, jonka sisällä CDA R2 -asiakirjat palautetaan, on kuvattu implementointioppaan sivulla Profiilit.

Hakuoperaatio on onnistunut myös silloin, jos vastauksena ei palaudu yhtään asiakirjaa. Tällöin hakutulosten määrä (total) on nolla.

Esimerkki Bundle resurssi-instanssista, jonka hakutulos on nolla (ei ole löytynyt hakuehtoja täyttäviä asiakirjoja):

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

Sivutettu vastaus

Sivutetun haun vastauksessa palautuu tiedot jatkohaun muodostamista varten:

• self: palautetun tulossivun haku ja siinä käytetyt parametrit
• next: seuraavan sivun hakemiseen tarvittava URL, joka sisältää jatkohaun parametrit
  • palautuu vain jos tulosjoukossa on vielä palautettavaa
  • URL sisältää alkuperäisen haun sekä jatkohakuun tarvittavan queryId-parametrin ja sen arvon
  • URL:sta kysymysmerkin jälkeen löytyvät parametrit on välitettävä sellaisenaan seuraavaa sivua haettaessa POST-pyynnön body-osassa, koska kysely sisältää henkilötunnuksen. (Katso myös jatkokyselyesimerkit sivulta Hakuparametrien käyttö.)
• Sivutus ei ole kaksisuuntainen, joten back-linkki ei ole käytössä.

Esimerkki haun vastauksessa palautuvista jatkohaun kannalta olennaisista tiedoista:

    "resourceType": "Bundle",
    "id": "073ce2b1-4c39-4cae-a479-ca59c8f74fef",
    "meta": {"lastUpdated": "2024-04-11T15:07:09"},
    "type": "searchset",
    "link": [
        {
            "relation": "self",
            "url": "[base][api]?patient:identifier=1.2.246.21|041222A953N"
        }, 
        {
            "relation": "next",
            "url": "[base][api]?patient:identifier=1.2.246.21|041222A953N&type=1&queryId=1.2.246.10.11559299.93.2009.109299685644658699
                  |Asiakirja|20190528133128|1.2.246.10.11559039.93.2009.109039488499488493"
        }
    ]
    ...
}

Mikäli edellisen esimerkin pohjalta muodostettaisiin jatkohaku, välitettäisiin POST-pyynnön body-osassa seuraavat parametrit:

patient:identifier=1.2.246.21|041222A953N&type=1&queryId=1.2.246.10.11559299.93.2009.109299685644658699|Asiakirja|20190528133128|1.2.246.10.11559039.93.2009.109039488499488493

Vastaussanoma virhetilanteessa

Virhetilanteissa vastauksena palautuu HTTP virhestatuskoodi sekä HTTP bodyssa OperationOutcome resurssi-instanssi, jolla ilmaistaan tarkempi virhe. HRP-palvelussa käytettävää OperationOutcome-resurssia ei ole profiloitu.

HTTP bodya ja OperationOutcome resurssi-instanssia ei kuitenkaan palauteta, mikäli hakusanoma on muodollisesti epävalidi tai auktorisointi on epäonnistunut esimerkiksi virheellisen tokenin takia. Näissä tapauksissa palautetaan pelkkä HTTP virhestatuskoodi. Esimerkkejä erilaisista virhevastauksista löytyy sivulta Virhevastauksia.

Kanta-palvelujen yhteisessä FHIR- ja REST-soveltamisoppaassa sivulla Kanta rajapinnan virhevastaus on kuvattu tarkemmin, miten Kanta-palvelut palauttaa virheilmoitukset OperationOutcome-resussilla.

Palautettavat potilastiedot asiakirjahaussa

Asiakirjahaussa palautetaan potilastietoja sisältäviä palvelutapahtuma- ja hoitoasiakirjoja. Palautuvien potilastietojen tyyppiin voi vaikuttaa haussa asiakirjan näkymäkoodilla (ks. sivu Haku). Palautettavien potilastietojen tarkat tietosisällöt on kuvattu Kansallisessa koodistopalvelussa.

Potilastiedot palautuvat FHIR-sanoman sisällä CDA R2 asiakirjoina. Implementointiopas ei kuvaa CDA R2 asiakirjojen rakennetta. CDA R2 -asiakirjojen rakenne on kuvattu mm. seuraavissa dokumenteissa:

• Potilastietovarannon CDA R2 Header
• Potilastietovarannon Kertomus ja lomakkeet
• Tietosisältökohtaiset CDA R2 määrittelyt
  • Kuvantamistutkimukset
  • Laboratoriotutkimukset
  • Optometria
  • Suun terveydenhuolto
  • Lääkityksen merkinnät
  • Ensihoito
  • Lähete- ja hoitopalaute
  • Terveys- ja hoitosuunnitelma
• Potilastietovarannon esimerkkiasiakirjat ja -sanomat.

Asiakirjojen rakennetta kuvaavat dokumentit ja linkit tietosisältöjen kuvauksiin Kansallisessa koodistopalvelussa on koottu Potilastietovarannon määrittelyhin kanta.fi-sivuille.

Palautettavat potilastiedot koostehaussa

Koostehaussa palautetaan diagnoosien, riskien, toimenpiteiden, rokotusten, fysiologisten mittausten, laboratoriotutkimusten ja kuvantamistutkimusten koostetietoja. Koostehaussa palautuvien koostetietojen tyyppiin vaikutetaan koostenäkymän koodilla (ks. sivu Haku). Palautettavien potilastietojen tarkat tietosisällöt on kuvattu Kansallisessa koodistopalvelussa.

Koostetiedot palautuvat FHIR-sanoman sisällä CDA R2 asiakirjoina. Implementointiopas ei kuvaa CDA R2 asiakirjojen rakennetta. CDA R2 -asiakirjojen rakenne on kuvattu mm. seuraavissa dokumenteissa:

• Tiedonhallintapalvelun koosteet ja ylläpidettävät asiakirjat

Asiakirjojen rakennetta kuvaava dokumentti ja linkit tietosisältöjen kuvauksiin Kansallisessa koodistopalvelussa on koottu Potilastietovarannon määrittelyjen sivulle Keskeiset terveystiedot.