Asiakirjahakujen vastaus

HTTP vastauksen tiedot palautetaan HTTP header- ja body-osuuksiin jaettuna. Tällä sivulla kuvataan nämä osuudet tarkemmin.

HTTP-vastauksen header

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

HTTP-vastauksen header esimerkki

HTTP/1.1 200 
x-request-id: f3a7c9e2-8b1d-4c6f-9d3a-2e6f5b4a9c1e
content-type: application/fhir+json;charset=UTF-8
transfer-encoding: chunked
date: Fri, 10 Oct 2025 11:53:04 GMT

HTTP-vastauksen body

Onnistuneen hakuoperaation vastauksena palautuu Bundle resurssi-instanssi, joka on tyypiltään searchset.

Bundle-resurssin total-kenttä kertoo, kuinka monta hakuehtoihin täsmäävää tulosta löydettiin haun käsittelyn aloitushetkellä. Se siis kertoo arvion jäljellä olevista asiakirjoista, vastaukselle poimitut mukaan luettuna. Vastaukseen poimittujen asiakirjojen määrä voi poiketa total-arvosta, jos esimerkiksi asiakirjat eivät mahdu yhteen vastaukseen tai joidenkin asiakirjojen välitys epäonnistuu jostakin syystä.

Bundle-resurssin entry:n listasta löytyvät vastaukseen poimitut välitykset, jotka ovat Communication resurssi-instansseja. Communication -resurssi-instanssin payload-kenttä pitää sisällään haetun asiakirjan base64-enkoodattuna. Jos hakuehdoilla löytyy useampi välitettävä asiakirja, niiden kaikkien tiedot palautuvat omina resursseinaan entry-listassa.

Esimerkit onnistuneen haun vastaussanomasta

1. Kun kaikki välitettävät asiakirjat voidaan palauttaa yhdessä vastauksessa

Esimerkki on pitkä, joten sivun luettavuuden vuoksi voit avata / sulkea esimerkin tästä
{
"resourceType": "Bundle",
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "[base]/Communication/$get-persons-documents"
}
],
"entry": [
{
"fullUrl": "urn:uuid:f56f4b51-55c6-4b37-99bb-da7b67e943b0",
"resource": {
"resourceType": "Communication",
"id": "f56f4b51-55c6-4b37-99bb-da7b67e943b0",
"meta": {
"profile": [
"https://kvp.kanta.fi/fhir/StructureDefinition/valitys"
]
},
"contained": [
{
"resourceType": "Patient",
"id": "bf843f64-0deb-4cc5-bf4f-320486c138b7",
"identifier": [
{
"use": "official",
"system": "urn:oid:1.2.246.21",
"value": "030559-914N"
}
]
}
],
"basedOn": [
{
"identifier": {
"system": "urn:ietf:rfc:3986",
"value": "urn:uuid:83638f9a-e505-42fa-b55f-51f3ad15fc19"
}
}
],
"status": "in-progress",
"subject": {
"reference": "#bf843f64-0deb-4cc5-bf4f-320486c138b7"
},
"recipient": [
{
"identifier": {
"system": "urn:oid:1.2.246.537.6.40191.201701",
"value": "1.2.246.10.10317159"
}
}
],
"sender": {
"identifier": {
"system": "urn:ietf:rfc:3986",
"value": "urn:oid:1.2.246.10.55612120.10.0"
}
},
"reasonCode": [
{
"coding": [
{
"system": "urn:oid:1.2.246.537.6.40192.2012",
"code": "1"
}
]
}
],
"payload": [
{
"contentAttachment": {
"contentType": "text/xml",
"data": "UEQ5NGJXd......"
}
}
]
},
"response": {
"status": "200 OK",
"lastModified": "2025-10-08T10:09:59.577+00:00"
}
}
]
}

2. Kun kaikkia välitettäviä asiakirjoja ei voida palauttaa yhdessä vastauksessa (välitettäviä asiakirjoja enemmän kuin 100)

Vastauksen rakenne on identtinen edeltävän esimerkin kanssa, lukuunottamatta link-rakennetta, joka sisältää seuraavan asiakirjaerän hakuun tarvittavan linkin, jonka relation-avaimen arvona on next. Kyseinen linkki on jatkohaun endpoint, joka ilmaisee seuraavaksi haettavan tulosjoukon avaimen. Haku tehdään täsmälleen samoilla parametreilla kuin alkuperäinen haku ja hakua toistetaan niin kauan kuin tämä linkkirakenne on mukana vastauksessa.

Huomaathan, ettei alla olevan mallin entry-rakenteen sisältö ole todellisen mallin mukainen. Rakenteen sisältö on typistetty luoettavuuden helpottamiseksi, sillä ainoa olennainen eroavaisuus löytyy link-rakenteesta.

{
"resourceType": "Bundle",
"id": "073ce2b1-4c39-4cae-a479-ca59c8f74fef",
"total": 358,
"type": "searchset",
"link": [
{
"relation": "self",
"url": "[base]/Communication/$get-all-documents"
},
{
"relation": "next",
"url": "[base]/Communication/$get-all-documents&result_set_key=f352577a-b4e8-4b8b-99dd-90f7fb018555"
}
],
"entry": [
{
"resource": {
"resourceType": "Communication",
"id": "1-2-3",
"status": "entered-in-error",
"subject": {
"reference": "Tämä resource-rakenne on luettavuuden helpottamiseksi typistetty ja epävalidi täyte."
}
}
}
]
}

3. Kun välitetäviä asiakirjoja ei ole

Hakuoperaatio on onnistunut myös silloin, jos vastauksena ei palaudu yhtään välitystä. Tällöin Kysely- ja välityspalvelu palauttaa HTTP-statuskoodin 200 OK ja Bundle-resurssin, jossa hakutulosten määrä total = 0.

Esimerkki bundle-resurssista, jonka hakutulos on nolla.

{
"resourceType": "Bundle",
"id": "073ce2b1-4c39-4cae-a479-ca59c8f74fef",
"total": 0,
"type": "searchset",
"link": [
{
"relation": "self",
"url": "[base]/Communication/$get-all-documents"
}
]
}

Vastaussanoma virhetilanteessa

Virhetilanteissa vastauksena palautuu HTTP-virhestatuskoodi sekä HTTP-bodyssa OperationOutcome resurssi-instanssi, jolla ilmaistaan tarkempi virhe.

Vastaussanoma virhetilanteessa-sivulla on kuvattu tarkemmin, miten Kysely- ja välityspalvelu palauttaa virheilmoitukset OperationOutcome-resurssilla.