API Reference

The SecureHealth API provides comprehensive access to patient data, appointments, and system functionality. All API endpoints are secured with session-based authentication and implement role-based access control.

Base URL

https://api.securehealth.dev/v1

Authentication

Session-Based Authentication

SecureHealth uses PHP sessions for API authentication instead of JWT tokens. This provides better security for healthcare applications and integrates seamlessly with Symfony's security system.

Session-Based Authentication

All API requests require an active user session. Sessions are managed automatically through cookies and provide secure authentication for healthcare applications.

Login Endpoint

POST /auth/login
Content-Type: application/json

{
  "email": "doctor@securehealth.dev",
  "password": "password123"
}

Response

{
  "success": true,
  "user": {
    "id": "user_123",
    "email": "doctor@securehealth.dev",
    "roles": ["ROLE_DOCTOR"],
    "firstName": "Dr. Jane",
    "lastName": "Smith"
  },
  "sessionId": "session_abc123"
}

Session Management

Logout Endpoint

POST /auth/logout

Response

{
  "success": true,
  "message": "Logged out successfully"
}

Session Security

Session Security Features

Secure Cookies: Sessions use secure, HTTP-only cookies
CSRF Protection: Cross-site request forgery protection
Session Timeout: Automatic session expiration for security
Session Regeneration: Session ID regeneration on login
Redis Storage: Sessions stored in Redis for scalability

Session Configuration

Timeout: 30 minutes of inactivity
Regeneration: On each login
Storage: Redis cluster for high availability
Encryption: Session data encrypted at rest

Error Handling

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "email",
      "message": "Invalid email format"
    }
  }
}

HTTP Status Codes

200 OK: Request successful
201 Created: Resource created successfully
400 Bad Request: Invalid request data
401 Unauthorized: Authentication required
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
422 Unprocessable Entity: Validation errors
500 Internal Server Error: Server error

Patient Management

List Patients

Endpoint

GET /patients

Headers

Cookie: PHPSESSID=<session_id>

Query Parameters

page (optional): Page number (default: 1)
limit (optional): Items per page (default: 20)
search (optional): Search term
role (optional): Filter by role

Response

{
  "data": [
    {
      "id": "patient_123",
      "patientId": "PAT-12345",
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1990-05-15",
      "email": "john.doe@email.com",
      "phone": "+1-555-123-4567"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Get Patient Details

Endpoint

GET /patients/{id}

Headers

Cookie: PHPSESSID=<session_id>

Response

{
  "id": "patient_123",
  "patientId": "PAT-12345",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-05-15",
  "email": "john.doe@email.com",
  "phone": "+1-555-123-4567",
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zipCode": "12345"
  },
  "medicalHistory": "Patient has diabetes...",
  "labResults": [
    {
      "testDate": "2024-01-15",
      "testType": "Blood Glucose",
      "result": "150 mg/dL",
      "normalRange": "70-100 mg/dL"
    }
  ],
  "prescriptions": [
    {
      "medication": "Metformin",
      "dosage": "500mg",
      "frequency": "Twice daily",
      "startDate": "2024-01-01",
      "endDate": "2024-12-31"
    }
  ],
  "appointments": [
    {
      "date": "2024-01-15",
      "doctor": "Dr. Smith",
      "type": "Follow-up",
      "notes": "Regular checkup"
    }
  ]
}

Create Patient

Endpoint

POST /patients

Headers

Cookie: PHPSESSID=<session_id>
Content-Type: application/json

Request Body

{
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-05-15",
  "email": "john.doe@email.com",
  "phone": "+1-555-123-4567",
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zipCode": "12345"
  },
  "insurance": {
    "provider": "Blue Cross",
    "policyNumber": "BC123456789",
    "groupNumber": "GRP001"
  }
}

Response

{
  "id": "patient_123",
  "patientId": "PAT-12345",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-05-15",
  "email": "john.doe@email.com",
  "phone": "+1-555-123-4567",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Update Patient

Endpoint

PUT /patients/{id}

Headers

Cookie: PHPSESSID=<session_id>
Content-Type: application/json

Request Body

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@newemail.com",
  "phone": "+1-555-987-6543",
  "address": {
    "street": "456 Oak Ave",
    "city": "Newtown",
    "state": "CA",
    "zipCode": "54321"
  }
}

Response

{
  "id": "patient_123",
  "patientId": "PAT-12345",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@newemail.com",
  "phone": "+1-555-987-6543",
  "address": {
    "street": "456 Oak Ave",
    "city": "Newtown",
    "state": "CA",
    "zipCode": "54321"
  },
  "updatedAt": "2024-01-15T11:00:00Z"
}

Delete Patient

Endpoint

DELETE /patients/{id}

Headers

Cookie: PHPSESSID=<session_id>

Response

{
  "message": "Patient deleted successfully"
}

Medical Records

Get Medical History

Endpoint

GET /patients/{id}/medical-history

Headers

Cookie: PHPSESSID=<session_id>

Response

{
  "medicalHistory": "Patient has diabetes type 2, diagnosed in 2020. Currently managed with Metformin. No known allergies. Family history of diabetes.",
  "diagnoses": [
    {
      "condition": "Diabetes Type 2",
      "diagnosedDate": "2020-03-15",
      "status": "Active",
      "notes": "Well controlled with medication"
    }
  ],
  "allergies": [
    {
      "allergen": "Penicillin",
      "reaction": "Rash",
      "severity": "Moderate"
    }
  ]
}

Update Medical History

Endpoint

PUT /patients/{id}/medical-history

Headers

Cookie: PHPSESSID=<session_id>
Content-Type: application/json

Request Body

{
  "medicalHistory": "Patient has diabetes type 2, diagnosed in 2020. Currently managed with Metformin and diet. No known allergies. Family history of diabetes.",
  "diagnoses": [
    {
      "condition": "Diabetes Type 2",
      "diagnosedDate": "2020-03-15",
      "status": "Active",
      "notes": "Well controlled with medication and diet"
    }
  ]
}

Response

{
  "message": "Medical history updated successfully",
  "updatedAt": "2024-01-15T11:30:00Z"
}

Get Lab Results

Endpoint

GET /patients/{id}/lab-results

Headers

Cookie: PHPSESSID=<session_id>

Query Parameters

startDate (optional): Start date for results
endDate (optional): End date for results
testType (optional): Filter by test type

Response

{
  "labResults": [
    {
      "id": "lab_123",
      "testDate": "2024-01-15",
      "testType": "Blood Glucose",
      "result": "150 mg/dL",
      "normalRange": "70-100 mg/dL",
      "status": "High",
      "notes": "Patient fasting"
    },
    {
      "id": "lab_124",
      "testDate": "2024-01-15",
      "testType": "HbA1c",
      "result": "7.2%",
      "normalRange": "<7.0%",
      "status": "High",
      "notes": "3-month average"
    }
  ]
}

Add Lab Result

Endpoint

POST /patients/{id}/lab-results

Headers

Cookie: PHPSESSID=<session_id>
Content-Type: application/json

Request Body

{
  "testDate": "2024-01-15",
  "testType": "Blood Glucose",
  "result": "150 mg/dL",
  "normalRange": "70-100 mg/dL",
  "status": "High",
  "notes": "Patient fasting"
}

Response

{
  "id": "lab_125",
  "testDate": "2024-01-15",
  "testType": "Blood Glucose",
  "result": "150 mg/dL",
  "normalRange": "70-100 mg/dL",
  "status": "High",
  "notes": "Patient fasting",
  "createdAt": "2024-01-15T12:00:00Z"
}

Prescription Management

Get Prescriptions

Endpoint

GET /patients/{id}/prescriptions

Headers

Cookie: PHPSESSID=<session_id>

Query Parameters

status (optional): Filter by status (active, inactive, all)

Response

{
  "prescriptions": [
    {
      "id": "prescription_123",
      "medication": "Metformin",
      "dosage": "500mg",
      "frequency": "Twice daily",
      "startDate": "2024-01-01",
      "endDate": "2024-12-31",
      "status": "Active",
      "prescribedBy": "Dr. Smith",
      "pharmacy": "CVS Pharmacy"
    }
  ]
}

Create Prescription

Endpoint

POST /patients/{id}/prescriptions

Headers

Cookie: PHPSESSID=<session_id>
Content-Type: application/json

Request Body

{
  "medication": "Metformin",
  "dosage": "500mg",
  "frequency": "Twice daily",
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "pharmacy": "CVS Pharmacy",
  "instructions": "Take with food"
}

Response

{
  "id": "prescription_124",
  "medication": "Metformin",
  "dosage": "500mg",
  "frequency": "Twice daily",
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "status": "Active",
  "prescribedBy": "Dr. Smith",
  "pharmacy": "CVS Pharmacy",
  "instructions": "Take with food",
  "createdAt": "2024-01-15T12:30:00Z"
}

Update Prescription

Endpoint

PUT /prescriptions/{id}

Headers

Cookie: PHPSESSID=<session_id>
Content-Type: application/json

Request Body

{
  "dosage": "1000mg",
  "frequency": "Twice daily",
  "instructions": "Take with food, monitor blood sugar"
}

Response

{
  "id": "prescription_124",
  "medication": "Metformin",
  "dosage": "1000mg",
  "frequency": "Twice daily",
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "status": "Active",
  "prescribedBy": "Dr. Smith",
  "pharmacy": "CVS Pharmacy",
  "instructions": "Take with food, monitor blood sugar",
  "updatedAt": "2024-01-15T13:00:00Z"
}

Appointment Management

List Appointments

Endpoint

GET /appointments

Headers

Cookie: PHPSESSID=<session_id>

Query Parameters

patientId (optional): Filter by patient ID
doctorId (optional): Filter by doctor ID
startDate (optional): Start date for appointments
endDate (optional): End date for appointments
status (optional): Filter by status (scheduled, completed, cancelled)

Response

{
  "appointments": [
    {
      "id": "appointment_123",
      "patientId": "patient_123",
      "patientName": "John Doe",
      "doctorId": "doctor_456",
      "doctorName": "Dr. Smith",
      "date": "2024-01-15",
      "time": "10:00",
      "type": "Follow-up",
      "status": "Scheduled",
      "notes": "Regular checkup"
    }
  ]
}

Create Appointment

Endpoint

POST /appointments

Headers

Cookie: PHPSESSID=<session_id>
Content-Type: application/json

Request Body

{
  "patientId": "patient_123",
  "doctorId": "doctor_456",
  "date": "2024-01-20",
  "time": "14:00",
  "type": "Follow-up",
  "notes": "Regular checkup"
}

Response

{
  "id": "appointment_124",
  "patientId": "patient_123",
  "patientName": "John Doe",
  "doctorId": "doctor_456",
  "doctorName": "Dr. Smith",
  "date": "2024-01-20",
  "time": "14:00",
  "type": "Follow-up",
  "status": "Scheduled",
  "notes": "Regular checkup",
  "createdAt": "2024-01-15T13:30:00Z"
}

Update Appointment

Endpoint

PUT /appointments/{id}

Headers

Cookie: PHPSESSID=<session_id>
Content-Type: application/json

Request Body

{
  "date": "2024-01-21",
  "time": "15:00",
  "notes": "Rescheduled due to conflict"
}

Response

{
  "id": "appointment_124",
  "patientId": "patient_123",
  "patientName": "John Doe",
  "doctorId": "doctor_456",
  "doctorName": "Dr. Smith",
  "date": "2024-01-21",
  "time": "15:00",
  "type": "Follow-up",
  "status": "Scheduled",
  "notes": "Rescheduled due to conflict",
  "updatedAt": "2024-01-15T14:00:00Z"
}

Cancel Appointment

Endpoint

DELETE /appointments/{id}

Headers

Cookie: PHPSESSID=<session_id>

Response

{
  "message": "Appointment cancelled successfully"
}

User Management

List Users

Endpoint

GET /users

Headers

Cookie: PHPSESSID=<session_id>

Query Parameters

role (optional): Filter by role
status (optional): Filter by status (active, inactive)

Response

{
  "users": [
    {
      "id": "user_123",
      "email": "doctor@securehealth.dev",
      "firstName": "Dr. Jane",
      "lastName": "Smith",
      "roles": ["ROLE_DOCTOR"],
      "department": "Cardiology",
      "isActive": true,
      "lastLogin": "2024-01-15T10:30:00Z"
    }
  ]
}

Create User

Endpoint

POST /users

Headers

Cookie: PHPSESSID=<session_id>
Content-Type: application/json

Request Body

{
  "email": "nurse@securehealth.dev",
  "firstName": "Sarah",
  "lastName": "Johnson",
  "roles": ["ROLE_NURSE"],
  "department": "Cardiology",
  "password": "securepassword123"
}

Response

{
  "id": "user_124",
  "email": "nurse@securehealth.dev",
  "firstName": "Sarah",
  "lastName": "Johnson",
  "roles": ["ROLE_NURSE"],
  "department": "Cardiology",
  "isActive": true,
  "createdAt": "2024-01-15T14:30:00Z"
}

Audit Logs

Get Audit Logs

Endpoint

GET /audit-logs

Headers

Cookie: PHPSESSID=<session_id>

Query Parameters

userId (optional): Filter by user ID
action (optional): Filter by action
startDate (optional): Start date for logs
endDate (optional): End date for logs
resourceType (optional): Filter by resource type

Response

{
  "auditLogs": [
    {
      "id": "audit_123",
      "timestamp": "2024-01-15T10:30:00Z",
      "user": {
        "id": "user_123",
        "email": "doctor@securehealth.dev",
        "role": "ROLE_DOCTOR"
      },
      "action": "VIEW_PATIENT",
      "resource": {
        "type": "Patient",
        "id": "patient_123",
        "patientId": "PAT-12345"
      },
      "result": "SUCCESS",
      "ipAddress": "192.168.1.100"
    }
  ]
}

Rate Limiting

Rate Limits

Authentication: 5 requests per minute
General API: 100 requests per minute
Patient Data: 50 requests per minute
Audit Logs: 20 requests per minute

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248000

SDKs and Libraries

JavaScript SDK

JavaScript SDK Example
import { SecureHealthClient } from '@securehealth/js-sdk';

const client = new SecureHealthClient({
  baseUrl: 'https://api.securehealth.dev/v1',
  // Session-based authentication - cookies handled automatically
  withCredentials: true
});

// Login first to establish session
await client.auth.login({
  email: 'doctor@securehealth.dev',
  password: 'password123'
});

// Get patients
const patients = await client.patients.list();

// Get patient details
const patient = await client.patients.get('patient_123');

// Create patient
const newPatient = await client.patients.create({
  firstName: 'John',
  lastName: 'Doe',
  dateOfBirth: '1990-05-15',
  email: 'john.doe@email.com'
});

PHP SDK

PHP SDK Example
<?php

use SecureHealth\Client;

$client = new Client([
    'base_url' => 'https://api.securehealth.dev/v1',
    // Session-based authentication - cookies handled automatically
    'use_sessions' => true
]);

// Login first to establish session
$client->auth()->login([
    'email' => 'doctor@securehealth.dev',
    'password' => 'password123'
]);

// Get patients
$patients = $client->patients()->list();

// Get patient details
$patient = $client->patients()->get('patient_123');

// Create patient
$newPatient = $client->patients()->create([
    'firstName' => 'John',
    'lastName' => 'Doe',
    'dateOfBirth' => '1990-05-15',
    'email' => 'john.doe@email.com'
]);

Next Steps

Database Schema - MongoDB document structure
Security Implementation - Security patterns
Testing - Testing strategies
Deployment - Production deployment

Base URL​

Authentication​

Session-Based Authentication​

Login Process​

Session Management​

Session Security​

Error Handling​

Error Response Format​

HTTP Status Codes​

Patient Management​

List Patients​

Get Patient Details​

Create Patient​

Update Patient​

Delete Patient​

Medical Records​

Get Medical History​

Update Medical History​

Get Lab Results​

Add Lab Result​

Prescription Management​

Get Prescriptions​

Create Prescription​

Update Prescription​

Appointment Management​

List Appointments​

Create Appointment​

Update Appointment​

Cancel Appointment​

User Management​

List Users​

Create User​

Audit Logs​

Get Audit Logs​

Rate Limiting​

Rate Limits​

Rate Limit Headers​

SDKs and Libraries​

JavaScript SDK​

PHP SDK​

Next Steps​

Base URL

Authentication

Session-Based Authentication

Login Process

Session Management

Session Security

Error Handling

Error Response Format

HTTP Status Codes

Patient Management

List Patients

Get Patient Details

Create Patient

Update Patient

Delete Patient

Medical Records

Get Medical History

Update Medical History

Get Lab Results

Add Lab Result

Prescription Management

Get Prescriptions

Create Prescription

Update Prescription

Appointment Management

List Appointments

Create Appointment

Update Appointment

Cancel Appointment

User Management

List Users

Create User

Audit Logs

Get Audit Logs

Rate Limiting

Rate Limits

Rate Limit Headers

SDKs and Libraries

JavaScript SDK

PHP SDK

Next Steps