API Endpoints

All endpoints under /api/** require an active SMART session in the HTTP session store. They return JSON and are consumed by the Thymeleaf templates via fetch(). They are also available for integration with other platform modules.

TokenRefreshFilter fires before every /api/** handler — the access token is proactively refreshed if less than 120 seconds remain, so callers never receive a stale token error.

Base URL: http://localhost:8084

---

GET /api/immunizations

Returns the patient's complete vaccination history.

Response: 200 OK

[
  {
    "fhirId":                   "imm-001",
    "vaccineCode":              "140",
    "vaccineName":              "Influenza, seasonal, injectable",
    "vaccineSystem":            "http://hl7.org/fhir/sid/cvx",
    "occurrenceDate":           "2024-10-01",
    "lotNumber":                "LOT-2024-FLUVAX",
    "performerOrganisationRef": "Organization/org-gp-001",
    "performerDisplay":         "Anytown GP Practice",
    "doseNumber":               "1",
    "seriesName":               "Annual influenza",
    "status":                   "completed",
    "route":                    "IM",
    "site":                     "Left deltoid",
    "note":                     null,
    "patientReported":          false
  }
]

Only status=completed records are returned. Records sorted newest-first.

---

GET /api/recommendations

Returns vaccine forecast / schedule from ImmunizationRecommendation.

Response: 200 OK

[
  {
    "fhirId":                 "rec-001",
    "vaccineCode":            "45",
    "vaccineName":            "Hepatitis B",
    "vaccineSystem":          "http://hl7.org/fhir/sid/cvx",
    "forecastStatus":         "overdue",
    "dateCriterionDue":       "2024-01-15",
    "dateCriterionLatest":    "2024-04-15",
    "doseNumber":             "2",
    "seriesName":             "Hepatitis B 3-dose series",
    "seriesDosesRequired":    "3",
    "supportingImmunizationRefs": ["Immunization/imm-hepb-001"],
    "description":            "Second dose overdue"
  }
]

Sorted: overdue first, then by dateCriterionDue ascending.

---

GET /api/summary

Returns aggregate counts for the dashboard stat cards.

Response: 200 OK

{
  "totalVaccinations":     12,
  "totalRecommendations":   4,
  "overdueCount":           1,
  "dueSoonCount":           2,
  "patientName":            "Priya Kumar",
  "patientDob":             "1985-03-15"
}

overdueCount — recommendations where isOverdue() returns true.
dueSoonCount — recommendations where isDueWithin30Days() returns true (may overlap with overdue).

---

GET /api/session

Returns current session metadata and token expiry countdown.

Response: 200 OK

{
  "patientId":         "ePatient-8675309",
  "clinicianName":     "Dr. Jane Smith",
  "needPatientBanner": true,
  "scope":             "launch openid fhirUser patient/Patient.rs patient/Immunization.rs patient/ImmunizationRecommendation.rs",
  "secondsRemaining":  3420
}

Use secondsRemaining to drive client-side session expiry warnings.

---

GET /api/certificate/qr

Generates a WHO VDS-NC QR code for the current patient's completed vaccinations.

Query parameters:

Parameter	Type	Default	Description
size	int	300	QR code image dimensions in pixels (square)

Response: 200 OK

{
  "qrBase64": "iVBORw0KGgo...",
  "format":   "PNG"
}

The qrBase64 value is a standard Base64-encoded PNG. Use it in an HTML image tag:

<img src="data:image/png;base64,{qrBase64}" alt="Vaccination QR code"/>

Returns 500 Internal Server Error if QR generation fails (e.g. ZXing error with oversized payload).

---

Error responses

All /api/** endpoints return a structured error when the SMART session is missing:

{
  "code":    "no_session",
  "message": "No active SMART session"
}

HTTP	Code	When
401	no_session	No SmartLaunchContext in session
500	—	Unexpected server error (HAPI connection failure, QR generation error)

There is no 403 — scope enforcement happens at the HAPI FHIR layer. If the access token lacks patient/Immunization.rs, HAPI returns 403 and ImmunizationFhirService catches it and returns an empty list rather than propagating the error.

---

← UI Views · Deployment →