Haun vastaussanomat

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 tai history. Bundle-resurssi-instanssin tyyppi on searchset, kun hakeva järjestelmä on hakenut viimeisimmät versiot search-interaktiolla ja history, kun hakeva järjestelmä on hakenut kaikki versiot history-interaktiolla. Sosiaalihuollon asiakastietovarannon palauttaman Bundle-resurssi-instanssin tyyppi on aina searchset.

Kanta-palvelut ilmoittaa palautettujen hakutulosten määrän 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,
  "link" : [{
    "relation" : "self",
    "url" : "https://example.com/base/Observation?patient=347&_include=Observation.provenance&_count=2"
  },
  {
    "relation" : "next",
    "url" : "https://example.com/base/Observation?patient=347&searchId=ff15fd40-ff71-4b48-b366-09c706bed9d0&page=2"
  }
  ],
  "entry" : [{
    "resource" : {
      "resourceType" : "Observation",
      "id" : "1234"
    },
    "search" : {
      "mode" : "match"
    }
  },
  {
    "resource" : {
      "resourceType" : "Provenance",
      "id" : "2345"
    },
    "search" : {
      "mode" : "include"
    }
  },
    {
    "resource" : {
      "resourceType" : "Observation",
      "id" : "3456"
    },
    "search" : {
      "mode" : "match"
    }
    },
    {
    "resource" : {
      "resourceType" : "Provenance",
      "id" : "4567"
    },
    "search" : {
      "mode" : "include"
    }
  }
 ]
}

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,
}

Sivutettu vastaus

Sivutetun haun vastauksessa Kanta-palvelut palauttaa hakevalle järjestelmälle tarvittaessa tiedot next ja previous jatkohaun muodostamista varten.

{
    "resourceType": "Bundle",
    "type": "searchset",
    "link": [
        {
            "relation": "self",
            "url": ...
        },
        {
            "relation": next",
            "url": ...
        },
        {
            "relation": "previous",
            "url": ...
        }
    ],
    ...
}

Mitätöityjen toimintakykytietojen palautuminen hauissa

Sosiaalihuollon asiakastietovaranto ei palauta haussa asiakastietojärjestelmälle mitätöityjä merkintöjä toimintakyvystä tai toimintakykyarvioita. Sosiaalihuollossa rekisterinpitäjä voi hakea omassa rekisterissään olevat mitätöidyt merkinnät toimintakyvystä tai toimintakykyarviot Sosiaalihuollon asiakastietovarannon arkistonhoitajan käyttöliittymästä.

Potilastietovarannossa mitätöidyt merkinnät toimintakyvystä tai toimintakykyarviot palautetaan history-interaktiolla tehtävässä haussa. Potilastietovarannon määrittely tarkentuu vuonna 2026.

Vastaussanoma virhetilanteessa

Virhetilanteessa Kanta-palvelut palauttaa Bundle-resurssin entry-elementissä HTTP-virhestatuskoodin ja OperationOutcome-resurssin, jolla ilmoitetaan tarkempi virhe. Kanta-palvelujen virhetilanteessa palauttama vastausssanoma on kuvattu Kanta yhteisten FHIR- ja REST-rajapintamäärittelyjen soveltamisoppaassa sivulla Kanta-rajapinnan virhevastaus.