API Overview

Introduction to the OpenEyes REST API

Introduction

The OpenEyes API provides programmatic access to patient records, clinical events, and other ophthalmology data. The API follows REST principles and returns JSON-formatted responses.

This API enables integration with external systems, diagnostic devices, and third-party applications while maintaining security and data integrity.

Base URL

All API endpoints are prefixed with:

/api/v1/

Example full URL:

https://your-openeyes-instance.com/api/v1/patient/search

API Versioning

The OpenEyes API uses URL-based versioning. The current version is v1.

URL routing is configured to handle the following pattern:

api/v1/<controller>/<action>

Supported HTTP methods:

• GET - Retrieve data
• POST - Create or submit data
• PUT - Update existing data

Response Format

All API responses are returned in JSON format with appropriate HTTP status codes.

Success Response

{
  "id": 123,
  "first_name": "John",
  "last_name": "Smith",
  "dob": "1970-05-15"
}

Error Response

Error responses include descriptive messages:

{
  "success": 0,
  "message": {
    "field_name": "Error description"
  }
}

HTTP Status Codes

The API uses standard HTTP status codes defined in BaseApiController.php:

Status Code	Message	Description
200	OK	Request successful
401	Unauthorized	Authentication failed
403	Forbidden	Insufficient permissions
422	Unprocessable Entity	Invalid request data
500	Internal Server Error	Server-side error

Source reference: protected/modules/Api/controllers/BaseApiController.php:44-50

Headers

Required Headers

Content-Type: application/json
Authorization: Basic <base64_credentials>

Response Headers

All JSON responses include:

Content-Type: application/json

Unauthorized responses (401) include:

WWW-Authenticate: Basic realm="OpenEyes"

Error Handling

The API implements consistent error handling through the BaseApiController class:

• 401 Unauthorized: Invalid or missing authentication credentials
• 403 Forbidden: User lacks required permissions (OprnApi role)
• 422 Unprocessable Entity: Request syntax is valid but contains invalid data
• 500 Internal Server Error: System-level errors

Example Error Response

{
  "success": 0,
  "message": {
    "system": "Database connection failed"
  }
}

Rate Limiting

Currently, the OpenEyes API does not implement rate limiting at the framework level. However, administrators should configure rate limiting at the web server or reverse proxy level to prevent abuse.

API Modules

The API is organized into modules:

Core API Module

• Patient search
• Attachment display
• Digital signatures

Request Module

• External device integration
• Queue management for incoming data
• Event attachment handling

URL pattern for Request module:

api/v1/request/<controller>/<action>

Common Response Patterns

renderJSON Method

All API controllers use the renderJSON() method defined in BaseApiController.php:30-41:

public function renderJSON($status, $data)
{
    ob_clean();
    header('HTTP/1.1 ' . $status . ' ' . $this->_getStatusCodeMessage($status));
    header('Content-type: application/json');
    if ($status == 401) {
        header('WWW-Authenticate: Basic realm="OpenEyes"');
    }
    echo json_encode($data);
    \Yii::app()->end();
}

This ensures consistent JSON responses across all endpoints.

Next Steps

Authentication

Learn how to authenticate API requests

Patient API

Search and retrieve patient data

Events API

Manage clinical events and attachments