> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/appertafoundation/openeyes/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```json theme={null}
{
  "id": 123,
  "first_name": "John",
  "last_name": "Smith",
  "dob": "1970-05-15"
}
```

### Error Response

Error responses include descriptive messages:

```json theme={null}
{
  "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

```http theme={null}
Content-Type: application/json
Authorization: Basic <base64_credentials>
```

### Response Headers

All JSON responses include:

```http theme={null}
Content-Type: application/json
```

Unauthorized responses (401) include:

```http theme={null}
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

```json theme={null}
{
  "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`:

```php theme={null}
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

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/api/authentication">
    Learn how to authenticate API requests
  </Card>

  <Card title="Patient API" icon="user" href="/api/patients">
    Search and retrieve patient data
  </Card>

  <Card title="Events API" icon="calendar" href="/api/events">
    Manage clinical events and attachments
  </Card>
</CardGroup>