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öytyy kokonaisuudessaan palvelusta. 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:ietf:rfc:3986",
"value": "urn:oid: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": "PGEvPg=="
}
}
]
}
}
]
}

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

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.Kyseisen linkin url-osoitteessa on kaikki alkuperäiset hakuparametrit, joilla ensimmäinen sivu haettiin, sekä sivutusavain result_set_key, joka on seuraavan tulosjoukon avain. Jotta hakutulosten jatkuvuus säilyy, seuraavan sivun haussa tulee kutsua hakurajapintaa kaikilla next-linkissä annetuilla parametreilla.

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

{
"resourceType": "Bundle",
"id": "073ce2b1-4c39-4cae-a479-ca59c8f74fef",
"type": "searchset",
"total": 358,
"link": [
{
"relation": "self",
"url": "[base]/Communication/_search?_query=get-all-documents&organization=1.2.246.10.123456789&viewCode=urn:oid:1.2.246.537.6.12.2002|151&_lastUpdated=ge2025-10-01&_lastUpdated=le2025-10-15&reload=true"
},
{
"relation": "next",
"url": "[base]/Communication/_search?_query=get-all-documents&organization=1.2.246.10.123456789&viewCode=urn:oid:1.2.246.537.6.12.2002|151&_lastUpdated=ge2025-10-01&_lastUpdated=le2025-10-15&reload=true&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",
"type": "searchset",
"total": 0,
"link": [
{
"relation": "self",
"url": "[base]/Communication/_search?_query=get-all-documents&organization=1.2.246.10.123456789&viewCode=urn:oid:1.2.246.537.6.12.2002|151&reload=true&result_set_key=f352577a-b4e8-4b8b-99dd-90f7fb018555"
}
]
}

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.