Versiointi- ja vastaussanomat

Toimintakykytiedon uuden version tallentamisessa käytettävän HTTP-pyynnön tiedot lähetetään HTTP header- ja body-osuuksiin jaettuna. Tällä sivulla kuvataan nämä osuudet tarkemmin versioinnin osalta.

Tallennussanoma

Tallennussanoma lähetetään Kanta-palveluihin HTTP-pyyntönä (request) POST-metodilla FHIR-palvelun endpoint:in juureen. Versioinnissa käytetään POST-metodia, sillä HTTP body-osuudessa oleva FHIR-resurssi on Bundle, jonka tyyppi on transaction. Eri ympäristöjen käytettävät juuret ilmoitetaan palveluun liittyville tietojärjestelmätoimittajille erikseen eikä niitä julkisteta tässä soveltamisoppaassa.

HTTP-pyynnön header

HTTP-pyynnön tiedot lähetetään HTTP header- ja body-osuuksiin jaettuna. HTTP-pyynnön header-osuus sisältää Kanta FHIR HTTP header -dokumentin mukaisen HTTP-headerin ja JSON Web Tokenin. Potilastietovarantoon lähetettävän HTTP-pyynnön (request) tiedot ja niiden pakollisuudet on määritelty dokumentin Kanta FHIR HTTP-header taulukon 2.1 Kanta-palveluiden HTTP pyynnön header kentät sarakkeessa PTA ja Sosiaalihuollon asiakastietovarantoon lähetettävän HTTP-pyynnön sarakkeessa SHA. JSON Web Tokenin tiedot ja niiden pakollisuudet on määritelty dokumentin Kanta JSON Web Token taulukossa 4.1 Kanta-palveluiden JWT Claimit. Potilastietovarantoon lähetettävän JWT:n tiedot ja tietojen pakollisuudet on määritelty sarakkeessa PTA ja Sosiaalihuollon asiakastietovarantoon lähetettävän JWT:n sarakkeessa SHA.

HTTP-pyynnön body

HTTP-pyynnön body on kuvattu sivulla Tallennus- ja vastaussanomat. Merkinnän toimintakyvystä tai toimintakykyarvion uuden version tallentamisessa Observation-resurssista tallennetaan uusi versio ja Provenance-resurssista tallennetaan kokonaan uusi instanssi. Provenance-resurssi-instanssi on aina Observation-resurssi-instanssiin liittyen versiokohtainen.

Observation-resurssin osalta Bundle.entry.request.method-elementtien arvoksi laitetaan PUT ja Provenance-resurssin osalta POST.

HTTP-pyynnön body-osuuden rakentuminen uuden version tallentamisessa on kuvattu kuvassa 4.

Kuva 4 Toimintakykytietojen HTTP-pyynnön body-osuus uuden version tallennuksessa

Versiointi ja resurssin looginen tunniste (id)

Merkinnän toimintakyvystä tai toimintakykyarvion uuden version tallentamisessa Observation-resurssi-instanssin loogisena tunnisteena on käytettävä Kanta-palvelujen resurssi-instanssille luomaa resurssi-instanssin yksilöivää loogista tunnistetta (id).

Observation-resurssiin liittyvän Bundle.entry.request.ifMatch-elementin arvoksi on annettava resurssi-instanssin viimeisin versionumero eli Kanta-palvelujen haun vastaussanomassa resurssin response-elementin etag-kentässä palauttama versionumero. Uuden version tallentaminen onnistuu vain, kun ifMatch-elementissä välitetään versionumero, joka vastaa kyseisen merkinnän toimintakyvystä tai toimintakykyarvion viimeisintä eli voimassa olevaa versiota Kanta-palveluissa. Kanta-palvelut huolehtii muuten korvattavan resurssi-instanssin versioinnista.

Observation-Bundle.entry.request.url-elementin arvoksi on annettava viittaus korvattavan Observation-resurssi-instanssin loogiseen tunnisteeseen (id).

Merkinnän toimintakyvystä tai toimintakykyarvion uuden version tallentamisessa tallentavan järjestelmän on luotava Provenance-resurssi-instanssille väliaikainen looginen tunniste ja ilmoitettava se Provenancen-resurssiin liittyvässä Bundle.entry:n fullUrl-elementissä. Kanta-palvelut tuottaa toimintakykytietojen versioinnissa Provenance-resurssi-instanssille globaalisti yksilöivän tunnuksen ja korvaa tallentavan järjestelmän resurssi-instanssin fullUrl-elementissä ilmoittaman loogisen tunnisteen (id). Kanta-palvelut palauttaa tuottamansa resurssi-instanssin loogisen tunnisteen (id) vastaussanomassa onnistuneessa versioinnissa.

Alla on esimerkki uuden version tallentamisessa käytettävästä Bundle-resurssista ja sen sisällä olevista Observation- ja Provenance-resurssi-instansseista sekä uuden version tallentamisen osalta merkittävistä tiedoista.

Esimerkki uuden version tallennuksessa käytettävästä Bundle-resurssista

{
    "resourceType": "Bundle",
    "type": "transaction",
    "entry": [
        {
            "fullUrl": "urn:uuid:6aac45d1-6893-4bdf-827b-504faaca481d",
            "resource": {
                "resourceType": "Observation",
                "id": "6aac45d1-6893-4bdf-827b-504faaca481d",
                ...
            },
            "request": {
                "method": "PUT",
                "url": "urn:uuid:6aac45d1-6893-4bdf-827b-504faaca481d",
                "ifMatch": "W/\"1\""
            }
        },
        {
            "fullUrl": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf145"
            "resource": {
                "resourceType": "Provenance",
                ...
                "target": {
                    "reference": "Observation/6aac45d1-6893-4bdf-827b-504faaca481d/_history/2",
                    "display": "Merkintä toimintakyvystä"
                },
                ...
                "activity": {
                    "coding": {
                        "system": "urn:oid:1.2.246.537.5.40178.2008",
                        "code": "1",
                        "display": "Korjaus"
                    }
                }
            },
            "request": {
                "method": "POST",
                "url": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf145"
            }
        }
    ],
    {
        "signature": {
            ...
        }
    }
}

Vastaussanoma

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

Merkinnän toimintakyvystä tai toimintakykyarvion uuden version tallennuksessa Kanta-palvelut palauttaa tallentavalle järjestelmälle vastauksena Bundlen, jonka tyyppi on transaction-response. Uuden version onnistuneessa tallennuksessa Kanta-palvelut palauttaa Bundle-resurssin entry-elementin response-elementissä seuraavat tiedot:

• pääresurssin (Observation) status-elementissä ilmoitetaan resurssin tallennuksen HTTP-statuskoodi 200 OK.
• Provenance-resurssin status-elementissä ilmoitetaan resurssin tallennuksen HTTP-statuskoodi 201 CREATED.
• location-elementissä ilmoitetaan tallennetun resurssin nimi, Kanta-palvelujen tuottama yksilöivä tunnus resurssille ja resurssin versionumero.
• etag-elementissä ilmoitaan resurssin versionumero.

Esimerkki Kanta-palvelujen palauttamasta vastaussanomasta resurssin uuden version onnistuneessa tallennuksessa

{
    "resourceType": "Bundle",
    "type": "transaction-response",
    "entry": [
        {
            "fullUrl": "urn:uuid:6aac45d1-6893-4bdf-827b-504faaca481d",
            "response": {
                "status": "200 OK",
                "location": "Observation/6aac45d1-6893-4bdf-827b-504faaca481d/_history/2",
                "etag": "W/\"2\""
            }
        }, 
        {
            "fullUrl": "urn:uuid:2639da1f-e03c-4faf-aec0-6007c4de7267",
            "response": {
                "status": "201 Created",
                "location": "Provenance/2639da1f-e03c-4faf-aec0-6007c4de7267/_history/1",
                "etag": "W/\"1\""
            }
        }
    ]
}

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.