# API Reference ## Table of Contents - [Overview](#overview) - [Base URL & Authentication](#base-url--authentication) - [Configuration Endpoints](#configuration-endpoints) - [Extension Management](#extension-management) - [Icon Management](#icon-management) - [System Information](#system-information) - [Direct Resource Access](#direct-resource-access) - [Error Handling](#error-handling) - [Client Implementation](#client-implementation) ## Overview The 5q12's Indexer API provides configuration management, icon delivery, and resource updates for the indexer system. The API uses RESTful endpoints with JSON responses. ### API Features - **Configuration Management**: Version checking and updates - **Extension Mappings**: File type to configuration mappings - **Icon System**: File type icons and metadata - **Resource Delivery**: Stylesheets, fonts, and static files - **System Status**: Health checks and diagnostics ## Base URL & Authentication ### Base URL ``` https://api.indexer.ccls.icu ``` ### Authentication - **No authentication required** for current version - **Rate limiting**: Reasonable limits for normal usage - **HTTPS required**: All requests must use HTTPS ### Request Headers ```http User-Agent: 5q12-Indexer/1.0 Accept: application/json ``` ## Configuration Endpoints ### Get Configuration Get the complete configuration file with all settings. ```http GET /api.php?action=config ``` **Response:** ```json { "success": true, "config": { "version": "1.0", "main": { /* main settings */ }, "exclusions": { /* file type indexing */ }, "viewable_files": { /* file type viewing */ } }, "version": "1.0", "last_modified": 1640995200 } ``` **Use cases:** - Initial configuration download - Manual configuration updates - Backup/restore operations ### Version Check Check if a configuration update is available. ```http GET /api.php?action=versionCheck¤t_version={version} ``` **Parameters:** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `current_version` | string | Yes | Current configuration version | **Response (Update Available):** ```json { "success": true, "current_version": "1.0", "latest_version": "1.1", "update_needed": true, "message": "Update available: 1.0 -> 1.1", "config_url": "https://api.indexer.ccls.icu/api.php?action=config", "timestamp": "2025-01-10 15:30:00" } ``` **Response (No Update):** ```json { "success": true, "current_version": "1.0", "latest_version": "1.0", "update_needed": false, "message": "You have the latest version: 1.0", "timestamp": "2025-01-10 15:30:00" } ``` ## Extension Management ### Get Extension Mappings Returns file extension to configuration key mappings. ```http GET /api.php?action=extensionMappings&type={type} ``` **Parameters:** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string | No | `"all"`, `"indexing"`, or `"viewing"` (default: `"all"`) | **Response:** ```json { "success": true, "mappings": { "indexing": { "php": "index_php", "js": "index_js", "py": "index_py" }, "viewing": { "php": "view_php", "js": "view_js", "py": "view_py" } }, "indexing_count": 200, "viewing_count": 180 } ``` **Type-specific responses:** ```http GET /api.php?action=extensionMappings&type=indexing ``` Returns only indexing mappings with `indexing_count`. ```http GET /api.php?action=extensionMappings&type=viewing ``` Returns only viewing mappings with `viewing_count`. ### Get Extension Setting Get the configuration key for a specific file extension. ```http GET /api.php?action=getExtensionSetting&extension={ext}&type={type} ``` **Parameters:** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `extension` | string | Yes | File extension (without dot) | | `type` | string | No | `"indexing"` or `"viewing"` (default: `"indexing"`) | **Response:** ```json { "success": true, "extension": "php", "type": "indexing", "setting": "index_php", "found": true } ``` **Not found response:** ```json { "success": true, "extension": "unknownext", "type": "indexing", "setting": null, "found": false } ``` ## Icon Management ### List All Icons Get a complete list of available icon files. ```http GET /api.php?action=icons ``` **Response:** ```json { "success": true, "icons": [ { "filename": "php.png", "url": "https://api.indexer.ccls.icu/icons/php.png", "size": 2048, "last_modified": 1640995200 }, { "filename": "folder.png", "url": "https://api.indexer.ccls.icu/icons/folder.png", "size": 1534, "last_modified": 1640995200 } ], "count": 150 } ``` ### Get Specific Icon Get information about a specific icon file. ```http GET /api.php?action=icon&name={filename} ``` **Parameters:** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | Icon filename (e.g., "php.png") | **Response:** ```json { "success": true, "icon": { "filename": "php.png", "url": "https://api.indexer.ccls.icu/icons/php.png", "size": 2048, "last_modified": 1640995200 } } ``` ### Find Icon for File Type Find the appropriate icon for a file type or folder. ```http GET /api.php?action=findIcon&type={type}&extension={ext} ``` **Parameters:** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string | Yes | `"file"` or `"folder"` | | `extension` | string | Conditional | Required for files, ignored for folders | **Response:** ```json { "success": true, "type": "file", "extension": "php", "icon": { "filename": "php.png", "url": "https://api.indexer.ccls.icu/icons/php.png", "path": "/path/to/icons/php.png", "size": 2048, "last_modified": 1640995200 } } ``` **Folder example:** ```http GET /api.php?action=findIcon&type=folder ``` ### Get Icon Mappings Get the complete mapping of extensions to icon filenames. ```http GET /api.php?action=iconMappings ``` **Response:** ```json { "success": true, "mappings": { "php": "php.png", "js": "js.png", "py": "python.png", "folder": "folder.png" }, "count": 150 } ``` ## System Information ### API Status Get API health and status information. ```http GET /api.php?action=status ``` **Response:** ```json { "success": true, "service": "Indexer API", "version": "1.0", "timestamp": "2025-01-10 15:30:00", "config_exists": true, "icons_dir_exists": true, "icon_mappings_exists": true, "extension_mappings_exists": true, "icon_count": 150, "mapping_count": 200, "extension_mapping_count": 380, "config_last_modified": 1640995200, "mappings_last_modified": 1640995200 } ``` ### API Information Get general API information and available endpoints. ```http GET /api.php ``` **Response:** ```json { "success": true, "service": "Indexer API", "version": "1.0", "description": "API for the custom indexer project", "endpoints": { "versionCheck": { "url": "?action=versionCheck¤t_version={version}", "description": "Check if a config update is available", "method": "GET" }, "config": { "url": "?action=config", "description": "Get configuration file", "method": "GET" } }, "icon_base_url": "https://api.indexer.ccls.icu/icons/", "timestamp": "2025-01-10 15:30:00" } ``` ## Direct Resource Access ### Icon Files Direct access to icon files for display in the indexer. ```http GET /icons/{filename} ``` **Examples:** ``` GET /icons/php.png GET /icons/folder.png GET /icons/text.png ``` **Response:** Binary image data with appropriate MIME type. ### Stylesheets Access to CSS stylesheets and web fonts. ```http GET /style/{filename} ``` **Examples:** ``` GET /style/8d9f7fa8de5d3bac302028ab474b30b4.css GET /style/latin-400.woff2 ``` ### Configuration Files Direct access to configuration and mapping files. ```http GET /{filename} ``` **Examples:** ``` GET /config.json GET /extensionMap.json GET /icons.json ``` ## Error Handling ### Error Response Format All API endpoints return errors in a consistent format: ```json { "error": "Error message description", "status": 400 } ``` ### HTTP Status Codes | Code | Description | Common Causes | |------|-------------|---------------| | **200** | OK | Successful request | | **400** | Bad Request | Missing/invalid parameters | | **404** | Not Found | Resource doesn't exist | | **500** | Internal Server Error | Server-side error | ### Common Error Examples **Missing Parameters:** ```json { "error": "Extension parameter is required", "status": 400 } ``` **Resource Not Found:** ```json { "error": "Icon not found", "status": 404 } ``` **Invalid Configuration:** ```json { "error": "Invalid configuration file", "status": 500 } ``` ## Client Implementation ### Caching Strategy The indexer implements intelligent caching: | Endpoint | Cache Duration | Use Case | |----------|----------------|----------| | Configuration | 1 hour | Regular updates | | Version checks | 15 minutes | Frequent checks | | Extension mappings | 24 hours | Rarely change | | Icon data | 24 hours | Static resources | ### Timeout Recommendations | Request Type | Timeout | Reason | |--------------|---------|---------| | Configuration | 30 seconds | Large payload | | Icons | 15 seconds | Binary data | | Version checks | 10 seconds | Quick response needed | ### PHP Example ```php [ 'timeout' => 30, 'user_agent' => '5q12-Indexer/1.0' ] ]); $response = @file_get_contents($url, false, $context); if ($response === false) { return null; // Handle error appropriately } $data = json_decode($response, true); if (isset($data['error'])) { error_log("API Error: " . $data['error']); return null; } return $data; } // Usage examples $config = callIndexerAPI('config'); $versionCheck = callIndexerAPI('versionCheck', ['current_version' => '1.0']); $iconInfo = callIndexerAPI('findIcon', ['type' => 'file', 'extension' => 'php']); ?> ``` ### JavaScript Example ```javascript class IndexerAPI { constructor(baseUrl = 'https://api.indexer.ccls.icu') { this.baseUrl = baseUrl; } async call(endpoint, params = {}) { const url = new URL(`${this.baseUrl}/api.php`); url.searchParams.set('action', endpoint); Object.keys(params).forEach(key => { url.searchParams.set(key, params[key]); }); try { const response = await fetch(url, { method: 'GET', headers: { 'User-Agent': '5q12-Indexer/1.0' }, timeout: 30000 }); if (!response.ok) { throw new Error(`HTTP ${response.status}`); } const data = await response.json(); if (data.error) { throw new Error(data.error); } return data; } catch (error) { console.error('API call failed:', error); return null; } } // Convenience methods async getConfig() { return this.call('config'); } async checkVersion(currentVersion) { return this.call('versionCheck', { current_version: currentVersion }); } async findIcon(type, extension = '') { return this.call('findIcon', { type, extension }); } } // Usage const api = new IndexerAPI(); const config = await api.getConfig(); const versionCheck = await api.checkVersion('1.0'); ``` ### Error Handling Best Practices 1. **Always check for errors** in API responses 2. **Implement fallback behavior** for failed requests 3. **Cache successful responses** to reduce API calls 4. **Log errors appropriately** for debugging 5. **Handle network timeouts** gracefully ### Rate Limiting Considerations - **Normal usage**: No strict limits - **Bulk requests**: Should be avoided - **Cache responses**: Locally when possible - **Respect server resources**: Don't make unnecessary calls --- **Related Documentation:** - [Configuration Guide](configuration.md) - Understanding configuration structure - [Installation Guide](installation.md) - API integration setup