Skip to main content

​
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 CodeMessageDescription
200OKRequest successful
401UnauthorizedAuthentication failed
403ForbiddenInsufficient permissions
422Unprocessable EntityInvalid request data
500Internal Server ErrorServer-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

Build docs developers (and LLMs) love

Get started for freeTalk to us