Chapter 4: API Interface Design for Elder Care Systems

Having established standardized data formats for elder profiles, vital signs, alerts, medications, and activities in the previous chapters, we now transition to examining how systems exchange this data in practice. Application Programming Interfaces (APIs) define the contracts through which software components communicate, specify request and response formats, establish authentication and authorization mechanisms, and govern error handling and edge cases. The WIA-SENIOR-001 API Interface Design phase specifies comprehensive RESTful HTTP APIs that enable interoperable elder care systems to create, retrieve, update, and delete data while maintaining security, reliability, and performance. This chapter explores the architectural decisions, endpoint specifications, and implementation patterns that enable seamless integration across the elder care technology ecosystem.

API design presents fundamental tradeoffs between competing goals: simplicity versus expressiveness, consistency versus optimization, security versus usability, and standardization versus flexibility. The WIA-SENIOR-001 API strikes careful balances across these dimensions, prioritizing developer experience and implementation ease while ensuring the expressiveness required for sophisticated care delivery applications. REST architectural principles provide the foundation, augmented with modern best practices from the healthcare IT, consumer technology, and standards communities. The result is an API that feels familiar to developers experienced with modern web services while addressing the unique requirements of elder care data management.

REST Architectural Principles

Representational State Transfer (REST) has emerged as the dominant architectural style for web APIs through its elegant simplicity, scalability, and alignment with web infrastructure. RESTful APIs treat resources—in our case elders, vital signs, alerts, medications, and activities—as first-class entities addressed by URLs and manipulated through standard HTTP methods. This resource-oriented approach maps naturally to elder care domain concepts and enables intuitive API designs that developers can understand and implement quickly.

Resource Identification Through URLs

Every entity in the WIA-SENIOR-001 data model corresponds to a resource accessible via a hierarchical URL structure. The base URL https://api.wia.org/senior-001 serves as the API root. Elder profiles are accessed via /elders/{elderId} where {elderId} is the UUID identifying a specific elder. Vital signs for an elder are accessed via /elders/{elderId}/vitals, creating a clear parent-child relationship. Individual vital signs records can be addressed as /vitals/{vitalsId} when needed. Alerts, medications, and activities follow similar patterns, creating a consistent and predictable URL structure throughout the API.

This hierarchical resource model enables both collection operations (listing all medications for an elder at /elders/{elderId}/medications) and individual resource operations (retrieving a specific medication at /medications/{medicationId}). Query parameters enable filtering, pagination, and sorting—for example, /elders/{elderId}/vitals?startDate=2025-01-01&endDate=2025-01-15 retrieves vital signs within a date range. This RESTful approach provides flexibility and power while maintaining simplicity and discoverability.

Table 4.1: Core API Resource Endpoints

Resource	Collection Endpoint	Individual Endpoint	Nested Access
Elder Profiles	GET /elders	GET /elders/{elderId}	N/A (root resource)
Vital Signs	GET /vitals	GET /vitals/{vitalId}	GET /elders/{elderId}/vitals
Alerts	GET /alerts	GET /alerts/{alertId}	GET /elders/{elderId}/alerts
Medications	GET /medications	GET /medications/{medId}	GET /elders/{elderId}/medications
Activities	GET /activities	GET /activities/{activityId}	GET /elders/{elderId}/activities

Standard HTTP Methods

RESTful APIs leverage HTTP's standard methods to perform operations on resources, providing consistent semantics across all endpoints. GET retrieves resource representations without modifying state—fetching an elder profile, retrieving vital signs history, listing alerts. POST creates new resources—registering a new elder, recording vital signs, generating alerts. PUT and PATCH update existing resources, with PUT replacing entire resources and PATCH performing partial updates. DELETE removes resources when appropriate and permitted by authorization rules.

This method-based approach enables powerful capabilities through simple combinations. Creating an elder profile: POST /elders with JSON payload containing profile data. Retrieving the profile: GET /elders/{elderId}. Updating emergency contact information: PATCH /elders/{elderId} with JSON containing only changed fields. Recording new vital signs: POST /vitals with vital signs data including elderId reference. The consistency across resources reduces cognitive load and enables generic client implementations that work across resource types.

Authentication and Authorization

Elder care systems handle Protected Health Information (PHI) subject to stringent security and privacy regulations including HIPAA, GDPR, and related frameworks. The WIA-SENIOR-001 API implements robust authentication to verify user and application identity, and fine-grained authorization to control access to sensitive data based on roles, relationships, and explicit consent grants.

Authentication Mechanisms

The standard supports multiple authentication mechanisms appropriate for different use cases. OAuth 2.0 and OpenID Connect provide industry-standard authentication for user-facing applications where elders, family caregivers, or healthcare providers authenticate through login flows. Service-to-service integration uses API keys or client credentials OAuth flows for system authentication. All authentication credentials are transmitted only over TLS 1.3 encrypted connections, and API keys must be treated as sensitive secrets stored securely rather than embedded in client-side code or version control.

// Authentication via Bearer token
GET /elders/elder-123/vitals/latest
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
X-WIA-Standard: SENIOR-001

// Authentication via API key
GET /elders/elder-123/vitals/latest
X-API-Key: wia_senior_key_abc123xyz789
X-WIA-Standard: SENIOR-001

Role-Based Access Control

Authorization implements role-based access control (RBAC) defining permissions for different user types. The ELDER role grants access to the elder's own data with read access to all profile, vitals, alerts, medications, and activities, and limited write access (for example, dismissing alerts or confirming medication taking). The FAMILY_CAREGIVER role grants read access to elder data based on explicit consent relationships, with limited write capabilities like resolving alerts or adding notes. The HEALTHCARE_PROVIDER role enables reading clinical data and writing medical information like diagnoses, medications, and care plans. The EMERGENCY_RESPONDER role provides emergency-access to critical information during active emergency alerts. System administrators have elevated privileges for account management and configuration.

Consent management enables granular control beyond role-based permissions. Elders can grant specific family members access to specific data types—for example, allowing a daughter to view vital signs and alerts but not detailed activity tracking to preserve privacy. Healthcare providers require explicit consent to access data, with audit logging recording all access. Emergency override provisions enable responders to access critical information during emergencies even without pre-existing consent, with comprehensive audit trails and post-emergency review processes.

Core API Endpoints

The WIA-SENIOR-001 API defines comprehensive endpoints for all elder care data operations. This section examines key endpoints in detail, establishing patterns that extend consistently across the full API surface.

Elder Profile Management

Elder profile endpoints enable creating new elder registrations, retrieving profile information, updating profiles as circumstances change, and archiving profiles when appropriate. Creating a profile requires comprehensive data collection while allowing optional fields to be omitted initially and added later. Response bodies echo the created resource with system-generated fields like ID and timestamps populated.

// Create elder profile
POST /elders
Content-Type: application/json

{
  "personalInfo": {
    "firstName": "Margaret",
    "lastName": "Johnson",
    "dateOfBirth": "1945-06-15",
    "gender": "female",
    "language": "en"
  },
  "medicalInfo": {
    "bloodType": "A+",
    "allergies": ["Penicillin"],
    "chronicConditions": ["Type 2 Diabetes Mellitus", "Essential Hypertension"]
  },
  "emergencyContacts": [
    {
      "priority": 1,
      "name": "Robert Johnson",
      "relationship": "Son",
      "phoneMobile": "+1-555-0199",
      "email": "robert.johnson@example.com"
    }
  ]
}

// Response: 201 Created
{
  "success": true,
  "data": {
    "id": "elder-123e4567",
    "personalInfo": { /* ... */ },
    "medicalInfo": { /* ... */ },
    "emergencyContacts": [ /* ... */ ],
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T10:30:00Z"
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

Profile retrieval returns complete elder profiles for authorized users. Partial updates via PATCH enable modifying specific profile sections without resending unchanged data. Common update operations include adding emergency contacts, updating addresses, modifying care preferences, and maintaining medication lists. The PATCH endpoint accepts partial JSON documents containing only changed fields, with deep merging semantics for nested objects.

Vital Signs Recording and Retrieval

Vital signs endpoints handle the high-volume data streams from wearable devices, home health equipment, and manual measurements. The recording endpoint accepts comprehensive vital signs objects with timestamp, elder ID, and measurement values. Retrieval endpoints support filtering by date range, vital sign type, and abnormality flags, with pagination for large result sets.

// Record vital signs
POST /vitals
Content-Type: application/json

{
  "elderId": "elder-123e4567",
  "timestamp": "2025-01-15T08:00:00Z",
  "heartRate": {"bpm": 72, "rhythm": "regular"},
  "bloodPressure": {"systolic": 128, "diastolic": 82},
  "temperature": {"value": 36.8, "unit": "celsius", "location": "oral"},
  "oxygenSaturation": {"percentage": 97}
}

// Get vital signs history with filters
GET /elders/elder-123e4567/vitals?startDate=2025-01-01&endDate=2025-01-15&type=bloodPressure

// Get latest vital signs (real-time monitoring)
GET /elders/elder-123e4567/vitals/latest

Table 4.2: Standard Query Parameters

Parameter	Type	Purpose	Example Values
startDate	ISO 8601 date	Filter results after date	2025-01-01
endDate	ISO 8601 date	Filter results before date	2025-01-15
limit	integer	Maximum results per page	50 (default: 25, max: 100)
offset	integer	Pagination offset	100
sort	string	Sort field and direction	timestamp:desc
filter	string	Resource-specific filters	severity=HIGH, resolved=false

Alert Management

Alert endpoints enable creating alerts from monitoring systems, retrieving alerts for dashboard displays, filtering by status and severity, and resolving alerts when addressed. The resolution workflow captures who resolved the alert, when, and optionally why, supporting quality improvement and false positive analysis.

// Get unresolved high-severity alerts
GET /elders/elder-123e4567/alerts?resolved=false&severity=HIGH

// Resolve alert with metadata
PATCH /alerts/alert-9876/resolve
Content-Type: application/json

{
  "resolvedBy": "user-caregiverId",
  "resolvedAt": "2025-01-15T14:45:00Z",
  "resolutionNotes": "Contacted elder via phone. Elevated heart rate due to climbing stairs. Elder feels fine, no intervention needed.",
  "falsePositive": false
}

Error Handling and Response Formats

Robust error handling enables clients to gracefully handle failures and present appropriate messaging to users. The WIA-SENIOR-001 API uses standard HTTP status codes with detailed error response bodies containing error codes, human-readable messages, and additional context. Success responses (2xx codes) return data in consistent formats with success flag, data payload, and timestamp. Error responses (4xx and 5xx codes) return error objects with code, message, and optional details array for validation errors.

// Success response format
{
  "success": true,
  "data": { /* resource data */ },
  "timestamp": "2025-01-15T10:30:00Z"
}

// Error response format
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid vital signs data",
    "details": [
      {"field": "heartRate.bpm", "error": "Value 300 exceeds maximum 200"},
      {"field": "timestamp", "error": "Timestamp cannot be in the future"}
    ]
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

HTTP Status Codes

Standard HTTP status codes communicate response semantics clearly. 200 OK indicates successful GET, PATCH, or DELETE requests. 201 Created confirms successful POST requests creating new resources, with the Location header containing the new resource's URL. 204 No Content acknowledges successful requests with no response body needed. 400 Bad Request signals client errors like invalid JSON, missing required fields, or validation failures. 401 Unauthorized indicates missing or invalid authentication. 403 Forbidden signals authorization failure—authenticated but insufficient permissions. 404 Not Found indicates requested resources don't exist. 429 Too Many Requests enforces rate limiting. 500 Internal Server Error reports server-side failures.

Pagination and Performance Optimization

Elder care systems accumulate large volumes of vital signs, activities, and alerts over time. Efficiently retrieving this data requires pagination, filtering, and optimization strategies. The standard specifies limit/offset pagination with configurable page sizes, default limits preventing accidental large queries, and response metadata indicating total result counts and pagination links.

// Paginated request
GET /elders/elder-123e4567/vitals?limit=50&offset=100

// Response with pagination metadata
{
  "success": true,
  "data": [ /* 50 vital signs records */ ],
  "pagination": {
    "limit": 50,
    "offset": 100,
    "total": 1543,
    "hasMore": true,
    "nextUrl": "/elders/elder-123e4567/vitals?limit=50&offset=150"
  },
  "timestamp": "2025-01-15T10:30:00Z"
}