API Overview

# Production
https://your-domain.com/api/v1

# Development  
http://localhost:3000/api/v1

# Demo Server
https://hmisdemo.itsolutionsuganda.com/api/v1

All API endpoints are prefixed with /api/v1. The API uses semantic versioning - breaking changes will increment the major version.

Most endpoints require JWT authentication. Include the token in the Authorization header:

# Login to get a token
curl -X POST https://api.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "password123"}'

# Response
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "role": "doctor"
  }
}

# Use the token in subsequent requests
curl https://api.example.com/api/v1/patients \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Public Endpoints (No Auth Required)

• POST /api/v1/auth/login - User login
• POST /api/v1/auth/register - User registration (if enabled)
• GET /api/v1/health - Health check
• GET /api/v1/updates/check - Check for updates
• POST /api/v1/license/validate - Validate license
• POST /api/v1/phone-home - Phone home heartbeat

All API responses follow a consistent format:

// Success Response
{
  "statusCode": 200,
  "data": { ... },
  "timestamp": "2026-04-10T00:00:00.000Z"
}

// Error Response
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed: email is required",
  "timestamp": "2026-04-10T00:00:00.000Z",
  "path": "/api/v1/patients"
}

// Paginated Response
{
  "statusCode": 200,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  },
  "timestamp": "2026-04-10T00:00:00.000Z"
}

API requests are rate limited to prevent abuse:

Rate limit headers are included in responses:

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