Haun vastaus

Haun HTTP vastaus (response)

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

Vastauksen HTTP header

Haun HTTP-vastauksen header-osuus noudattaa Kanta-palveluiden yhteistä Kanta FHIR HTTP header määrittelyä ja siinä kuvattuja tietoja.

Vastauksen HTTP body

Onnistuneen haun vastauksena palautuu Bundle resurssi-instanssi, joka on tyypiltään (type) searchset tai history:

• searchset, kun haetaan viimeisimmät versiot search-interaktiolla
• history, kun haetaan kaikki versiot history-interaktiolla

Ajanvarausten viimeisimpien versioiden haku palauttaa ajanvaraukset ajanvarauksen 1. version tallennusajan mukaan käänteisessä järjestyksessä.

Kaikkien versioiden haussa palautetaan yhden ajanvarauksen kaikki versiot. Lajittelu tehdään ajanvarauksen versioiden mukaan uusimmasta vanhimpaan.

Ajanvarauksen tiedot palautuvat Appointment-resursseissa ja niihin liittyvät metatiedot Provenance-resurseissa, nämä palautuvat Bundle-resurssin entry-elementin sisällä.

Esimerkki Bundle resurssi-instanssista, jonka sisällä palautuu kaksi ajanvarausta Appointment-resursseissa ja niiden metatiedot Provenance-resursseilla, kun haetaan viimeisimmät versiot:

{
    "resourceType": "Bundle",
    "type": "searchset",
    "link": [
        {
            "relation": "self",
            "url": ...
        }
    ],
    "entry": [
        {
            "resource": {
                "resourceType": "Appointment",
                ...
            }
        },
        {
            "resource": {
                "resourceType": "Provenance",
                ...
            }
        }, 
        {
            "resource": {
                "resourceType": "Appointment",
                ...
            }
        },
        {
            "resource": {
                "resourceType": "Provenance",
                ...
            }
        } 
    ]
}

Esimerkki vastaussanomasta, jossa välitetään tieto potilaan antaman luovutusluvan puuttumisesta, mikä vaikuttaa palautettavaan tulosjoukkoon.

{
    "resourceType": "Bundle",
    "type": "searchset",
    "link": [
        {
            "relation": "self",
            "url": ...
        }
    ],
    "entry": [
        {
            "resource": {
                "resourceType": "Appointment",
                ...
            }
        },
        {
            "resource": {
                "resourceType": "Provenance",
                ...
            }
        }, 
        {
            "resource": {
                "resourceType": "OperationOutcome",
                "id": "warning",
                "issue": [
                    {
                        "severity": "warning",
                        "code": "not-found",
                        "details": {
                            "text": "Luovutuslupa puuttuu"
                        }
                    }
                ]
            }
        }
    ]
}

Haku on onnistunut myös silloin, jos vastauksena ei palaudu yhtään Appointment- ja Provenance resurssi-instanssiparia.

Esimerkki Bundle resurssi-instanssista, kun ei ole löytynyt hakuehtoja täyttäviä ajanvarauksia:

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

Sivutettu vastaus

Kun kaikkia hakutuloksen mukaisia ajanvarauksia ei voida palauttaa yhdessä vastauksessa, ajanvarauksen vastaussanomassa palautetaan Bundle.link-elementissä jatkohakuun käytettävä linkki, jonka relation kentän arvo on next. Bundle.link‑elementin next‑linkki palautetaan vain, jos hakuehtojen mukaisia ajanvarauksia on vielä palauttamatta.

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

Jokainen jatkohaku on erillinen transaktio Potilastietovarannon näkökulmasta.

Jatkohaku on kuvattu Haku-sivulla kohdassa "Potilaan ajanvarausten jatkohaku".

Vastaussanoma virhetilanteessa

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

OperationOutcome-sivulla on kuvattu tarkemmin, miten Potilastietovaranto palauttaa virheilmoitukset OperationOutcome-resussilla.

Mitätöityjen ajanvarausten palautuminen hauissa

Mitätöidyt ajanvaraukset eivät palaudu normaaleissa hauissa (search-interaktiolla).

Asiakirjan korvauksen syy -luokituksen koodilla 4 mitätöidyt ajanvaraukset ovat haettavissa ainoastaan arkistonhoitajan käyttöliittymän kautta.

Asiakirjan korvauksen syy -luokituksen koodilla 2 mitätöidyt ajanvaraukset palautetaan, kun haetaan ajanvarausten kaikki versiot history-interaktiolla.

Alla on esimerkki mitätöidyn ajanvarauksen palautumisesta history-interaktion haussa, esimerkissä palautetaan ajanvaraus, jolle löytyy Potilastietovarannosta

• Ajanvarauksen mitätöinti syykoodilla 2
• Ajanvarauksen 2. versio
• Ajanvarauksen 1. versio

{
    "resourceType": "Bundle",
    "type": "history",
    "link": [
        {
            "relation": "self",
            "url": ...
        }
    ]
    "entry": [
        {
            "fullUrl": (kertoo, mitä resurssia entry koskee)
            "resource": {
                "resourceType": "Provenance",
                -- Mitätöinnissä käytetty provenance, joka sisältää mitätöijän tiedot, mitätöinnin syyn jne. --
            },
            "request": {
                "method": "POST",
                "url": "Provenance"
            }
        },
        {
            "fullUrl": (kertoo, mitä resurssia entry koskee)
            "request": {
                "method": "DELETE",
                "url": "Appointment/ce5ea340-adfd-40f2-87d4-a25e4f8bf201"
            }
        },
        {
            "fullUrl": (kertoo, mitä resurssia entry koskee)
            "resource": {
                "resourceType": "Appointment",
                "id": "ce5ea340-adfd-40f2-87d4-a25e4f8bf201",
                -- resurssin 2. versio --
            },
            "request": {
                "method": "PUT",
                "url": "Appointment/ce5ea340-adfd-40f2-87d4-a25e4f8bf201"
            }
        },
        {
            "fullUrl": (kertoo, mitä resurssia entry koskee)
            "resource": {
                "resourceType": "Provenance",
                -- 2. version provenance --
            },
            "request": {
                "method": "POST",
                "url": "Provenance"
            }
        },
        {
            "fullUrl": (kertoo, mitä resurssia entry koskee)
            "resource": {
                "resourceType": "Appointment",
                "id": "ce5ea340-adfd-40f2-87d4-a25e4f8bf201",
                -- resurssin 1. versio --
            },
            "request": {
                "method": "POST",
                "url": "Appointment"
            }
        },
        {
            "fullUrl": (kertoo, mitä resurssia entry koskee)
            "resource": {
                "resourceType": "Provenance",
                -- 1. version provenance --
            },
            "request": {
                "method": "POST",
                "url": "Provenance"
            }
        }
    ]
}