Vastauksen HTTP statuskoodit

Aluksi käytössä ovat seuraavat HTTP status koodit:

Näitä tullaan jatkossa tarkentamaan varsinkin virheisiin liittyvien statuskoodien osalta.

Vastauksen HTTP header

Vastauksessa palautuvat HTTP header-tiedot ovat seuraavat:

• Content-Type: paluu-sanoman muoto: application/fhir+json;charset=UTF-8
• X-Request-Id: vastaussanoman yksilöivä tunniste. esim.: 224895b7-39f0-48bb-81ce-63550d05b55d
• X-Correlation-Id (optional): pyyntösanoman yksilöinyt tunniste, esim.: 2a844596-bee7-4173-b469-cef15b1554c0

Lisätiedot X-alkuisista FHIR custom headereista: FHIR custom headers

Vastauksen HTTP header esimerkki

HTTP/1.1 200 OK
Content-Type: application/fhir+json;charset=UTF-8
X-Request-Id: 224895b7-39f0-48bb-81ce-63550d05b55d
X-Correlation-Id: 2a844596-bee7-4173-b469-cef15b1554c0

Vastauksen HTTP body

Onnistuneen pyynnön vastaukset

Onnistuneen hakuoperaation vastauksena palautuu Bundle resurssi-instanssi, joka on tyypiltään searchset (type). Bundle resurssin tiedoissa ilmaistaan hakutulosten määrä (total) sekä varsinaiset reseptin yksilöintitiedot MedicationRequest resurssi-instansseissa. Jokainen yksittäinen resepti on oma MedicationRequest instanssinssa Bundle rakenteen sisällä (entry).

Hakuoperaatio on onnistunut myös silloin, jos vastauksena ei palaudu yhtään MedicationRequest resurssi-instanssia. Tällöin hakutulosten määrä (total) on nolla.

Esimerkki Bundle resurssi-instanssista, jonka sisällä palautuu 3 MedicationRequest resurssi-instanssia

{
    "resourceType": "Bundle",
    "id": "92685db0-1b58-4cea-b1fa-289e8ab58892",
    "type": "searchset",
    "total": 3,
    "entry": [
        {
            "resource": {
                "resourceType": "MedicationRequest",
                ...
            }
        },
        {
            "resource": {
                "resourceType": "MedicationRequest",
                ...
            }
        },
        {
            "resource": {
                "resourceType": "MedicationRequest",
                ...
            }
        }
    ]
}

Esimerkki Bundle resurssi-instanssista, jonka hakutulos on nolla (esim. ei ole löytynyt hakuehtoja täyttäviä reseptin yksilöintietoja):

{
    "resourceType": "Bundle",
    "id": "073ce2b1-4c39-4cae-a479-ca59c8f74fef",
    "type": "searchset",
    "total": 0,
}

Palautuvat MedicationRequest resurssi-instanssit

Bundle resurssin sisällä palautuva yksittäinen MedicationRequest resurssi-instanssi sisältää yhden reseptin yksilöintitiedot. MedicationRequest-resurssista viitataan toisiin resursseihin. Näitä toisia resurssi-instansseja ovat Medication (lääkkeen tiedot), Patient (potilaan tiedot), Practitioner (määrääjän tiedot) ja Organization (määrääjän organisaation tiedot). Lisäksi palautuu PractitionerRole resurssi, jota tarvitaan, että voidaan ilmoittaa sekä Practitioner- että Organization-resurssit.

Hierarkia rakentuu seuraavasti:

• MedicationRequest
  • viittaus Medication resurssiin
  • viittaus Patient resurssiin
  • viittaus PractitionerRole resurssiin
    • viittaus Practitioner resurssiin
    • viittaus Organization resurssiin

Näistä kaikista resursseista löytyy tästä implementointioppaasta profiilit, joissa on määritelty reseptin yksilöintitietojen mappaus FHIR tietoihin, profiileissa tarvittavat laajennukset (Extension) sekä tarkempia soveltamisohjeita (esim. käytettävien koodistojen sidonta koodattuihin tietotyyppeihin).

Viitattavat resurssi-instanssit palautuvat kaikki aina hakuoperaation vastauksessa MedicationRequest resurssi-instanssin sisällä contained elementissä.

Esimerkki MedicationRequest resurssi-instanssista (riisuttu, josta näkyy muiden resurssien suhteet):

{
    "resourceType": "MedicationRequest",
    "id": "1.2.246.10.11587985.93.2009.17985416544561458",
    "contained": [
        {
            "resourceType": "Medication",
            "id": "1",
            ...
        },
        {
            "resourceType": "Patient",
            "id": "2",
            ...
        },
        {
            "resourceType": "PractitionerRole",
            "id": "3",
            "practitioner": {
                "reference": "#4"
            },
            "organization": {
                "reference": "#5"
            }
        },
        {
            "resourceType": "Practitioner",
            "id": "4",
            ...
        },
        {
            "resourceType": "Organization",
            "id": "5",
            ...
        }
    ],
    ...
    "status": "active",
    ...
    "medicationReference": {
        "reference": "#1"
    },
    "subject": {
        "reference": "#2"
    },
    "authoredOn": "2020-04-27T14:03:37+03:00",
    "requester": {
        "reference": "#3"
    },
    "dosageInstruction": ...
}

Virhetilanteeseen päätyneen pyynnön vastaus

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

OperationOutcome resurssista puuttuu vielä profiili. Seuraavaa kuvausta lukiessa kannattaa avata OperationOutcome-resurssi FHIR määrittelystä.

Yksittäinen virhe ilmoitetaan issue-elementissä. Severity-elementin arvo on virheissä ”error”, Code-elementtiin annetaan sopiva arvo FHIR koodistosta Issue Type ja varsinainen virhe ilmoitetaan Details-elementissä koodattuna. Details-elementin tietotyyppi on CodeableConcept, kyseinen tietotyyppi rakentuu Coding-tietotyypistä ja text-elementistä. Coding-tietotyypin elementeissä tiedot annetaan seuraavasti:

• system elementissä ilmoitetaan käytettävä koodisto
• code elementissä varsinainen virhekoodi
• display elementissä virhekoodia vastaava selite.

CodeableConcept tietotyypin text elementissä annetaan virheen tarkempi selite.

Esimerkki virheilmoituksesta, joka palautuu OperationOutcome resurssi-instanssissa (huom. alla olevaa virheiden koodistoa ei ole vielä lopullisesti sovittu eikä profiloitu OperationOutcome resurssiin):

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "details": {
                "coding": [
                    {
                        "system": "http://resepti.kanta.fi/fhir/prescription-errorcodes",
                        "code": "101015",
                        "display": "Virheellinen pakollinen tieto"
                    }
                ],
                "text": "clinicalDocument.code puuttuu"
            }
        }
    ]
}