EHR-001 // Developer Documentation Portal

EHR Patient API
Healthcare Interoperability Documentation

Developer-focused documentation for a fictional patient-facing EHR API. This portal demonstrates SMART on FHIR authentication, HIPAA-aware documentation language, clinical endpoint references, JSON examples, and healthcare information architecture.

StandardSMART on FHIR

AuthOAuth 2.0

FormatFHIR JSON

AudienceDevelopers

⚠

PHI Notice: This is a portfolio documentation project using fictional sample data. Real healthcare systems must protect protected health information according to organizational privacy, security, and compliance requirements.

Quick Navigation

Explore the Documentation

▶ EHR-002Getting StartedRegister an app, request scopes, authorize a patient, and make your first API call.GETTING-STARTED.md ◆ EHR-003AuthenticationOAuth 2.0 authorization and SMART on FHIR scope examples for patient data.AUTHENTICATION.md ⬡ API-100Clinical EndpointsAppointments, medications, lab results, and secure messaging endpoint references./endpoints ⚑ REF-201Error HandlingHealthcare-specific errors including consent required and restricted access scenarios.ERRORS.md

System Context

API Workflow

Patient Application
        │
        ▼
OAuth 2.0 Authorization
        │
        ▼
SMART on FHIR Scope Validation
        │
        ▼
EHR Patient API
        │
        ▼
Clinical Data Store
        │
        ▼
FHIR-compatible JSON Response

Healthcare Compliance Considerations

Concept	Documentation Relevance
`PHI`	Patient health data should be handled with clear privacy and security warnings.
`Minimum Necessary`	Applications should request only the scopes needed for the user task.
`Consent`	Some resources may require explicit patient authorization before access.
`Audit Logging`	Access to clinical data should be traceable in production healthcare systems.

EHR-002 // Developer Onboarding

Getting Started
Make Your First Patient API Request

This guide shows developers how to register an application, request authorization, receive an access token, and retrieve appointment data.

Developer onboarding workflow

1

Register your application. Configure a client ID, redirect URI, and approved SMART on FHIR scopes.

2

Request authorization. Redirect the patient to approve access to selected clinical resources.

3

Receive access token. Use the token in the Authorization header for API calls.

4

Make your first request. Retrieve appointments using GET /appointments.

Example Request

curl -X GET https://api.ehrportal.com/v1/appointments \
-H "Authorization: Bearer ACCESS_TOKEN"

EHR-003 // Authentication

OAuth 2.0 and
SMART on FHIR Authorization

Applications must request an access token with the appropriate scopes before accessing patient health data.

Authorization Header

Authorization: Bearer ACCESS_TOKEN

Example Scopes

Scope	Purpose
`patient/Appointment.read`	Read appointment data
`patient/MedicationRequest.read`	Read medication records
`patient/Observation.read`	Read lab results and observations
`patient/Communication.write`	Send secure messages

ⓘ

Security Note: Access tokens should never be exposed in public repositories, browser logs, or client-side source code.

API-100 // Clinical Endpoint Reference

Clinical Data
Endpoint Documentation

Endpoint reference for appointment, medication, lab result, and secure messaging workflows.

GET/appointmentspatient/Appointment.read

Retrieve upcoming and past patient appointment information.

{
  "appointments": [
    {
      "appointment_id": "APT-1001",
      "provider": "Dr. Sarah Johnson",
      "department": "Cardiology",
      "date": "2026-06-10",
      "time": "09:30 AM",
      "location": "Houston Medical Center"
    }
  ]
}

GET/medicationspatient/MedicationRequest.read

Retrieve active and past patient medication records.

{
  "medications": [
    {
      "medication_id": "MED-1001",
      "name": "Lisinopril",
      "dosage": "10 mg",
      "frequency": "Once daily",
      "status": "Active"
    }
  ]
}

GET/lab-resultspatient/Observation.read

Retrieve patient laboratory test results.

{
  "lab_results": [
    {
      "result_id": "LAB-1001",
      "test_name": "Hemoglobin A1C",
      "value": "6.1",
      "unit": "%",
      "reference_range": "4.0-5.6",
      "status": "High"
    }
  ]
}

POST/messagespatient/Communication.write

Send secure messages between patients and healthcare providers.

{
  "provider_id": "PROV-1001",
  "subject": "Prescription Refill Request",
  "message": "I would like to request a refill for my blood pressure medication."
}

REF-201 // Error Handling

Healthcare API
Error Handling Guide

Standard HTTP status codes and healthcare-specific errors for consent, access restriction, and expired authorization scenarios.

Status	Meaning	Healthcare Context
`400`	Bad Request	Invalid payload or missing required field
`401`	Unauthorized	Missing or expired access token
`403`	Consent Required	Patient authorization or access permission is required
`404`	Not Found	Requested clinical resource is unavailable
`500`	Server Error	Unexpected platform issue

Example Error Response

{
  "error": "Consent Required",
  "message": "Patient consent is required before accessing lab results."
}

REF-202 // Clinical Data Glossary

Healthcare API
Glossary for Developers

Plain-language definitions of healthcare interoperability and clinical data terms used throughout this documentation.

Term	Definition
`EHR`	Electronic Health Record, a digital system that stores patient health information.
`FHIR`	Fast Healthcare Interoperability Resources, a standard for exchanging healthcare information electronically.
`SMART on FHIR`	An authorization framework that allows apps to securely connect with EHR systems using OAuth 2.0.
`PHI`	Protected Health Information, data that can identify a patient and relates to health, care, or payment.
`Observation`	A FHIR resource commonly used for lab results, vitals, and clinical measurements.