Harper Best Practices

# Harper Best Practices for Secure API Design in Healthcare

## 1. Authentication & Authorization
- **Use OAuth 2.0** with JWT for API access. Avoid API keys for user-facing endpoints.
- **Example**: For a patient portal API, implement:
  ```http
  POST /oauth/token
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=client_credentials&client_id=healthapp-patient-portal&client_secret=XYZ123&scope=read:patient_data
  ```
- **Role-based access control (RBAC)**: Assign permissions like `patient:read`, `doctor:write`, and `admin:full` to API endpoints.

## 2. Data Validation
- **Validate all inputs** using Harper’s schema constraints (e.g., `NOT NULL`, `ENUM`, or custom validators).
- **Example**: Reject malformed HL7 FHIR data with:
  ```json
  {
    "error": "InvalidPatientID",
    "message": "Patient ID must be a 10-digit numeric value.",
    "code": 400
  }
  ```

## 3. Rate Limiting
- **Implement Harper’s rate limiter** with a sliding window for high-traffic endpoints (e.g., `/api/patient/{id}/records`).
- **Example**: Limit to 100 requests/minute per user:
  ```sql
  CREATE POLICY rate_limit_policy ON api_requests
  FOR SELECT USING (current_timestamp - created_at < interval '1 minute' AND user_id = current_user_id)
  WITH CHECK (count(*) < 100);
  ```

## 4. Logging & Monitoring
- **Log all API requests** with metadata (e.g., `user_id`, `endpoint`, `response_time`, `status_code`).
- **Example**: Use Harper’s structured logging to track:
  ```json
  {
    "timestamp": "2024-05-20T14:30:00Z",
    "level": "INFO",
    "service": "patient-api",
    "user_id": "pat_12345",
    "endpoint": "/api/patient/12345/prescriptions",
    "response_time_ms": 45,
    "status_code": 200
  }
  ```

## 5. Caching
- **Cache frequently accessed data** (e.g., patient demographics) using Harper’s Redis integration.
- **Example**: Cache patient records for 5 minutes with:
  ```sql
  SELECT * FROM patient_data WHERE id = $1;
  -- Cache result in Redis with key: `patient_data:12345`
  ```