API Reference

Overview
Base URL & Authentication
Configuration Endpoints
Extension Management
Icon Management
System Information
Direct Resource Access
Error Handling
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

User-Agent: 5q12-Indexer/1.0
Accept: application/json

Configuration Endpoints

Get Configuration

Get the complete configuration file with all settings.

GET /api.php?action=config

Response:

{
  "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.

GET /api.php?action=versionCheck&current_version={version}

Parameters:

Parameter	Type	Required	Description
`current_version`	string	Yes	Current configuration version

Response (Update Available):

{
  "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):

{
  "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.

GET /api.php?action=extensionMappings&type={type}

Parameters:

Parameter	Type	Required	Description
`type`	string	No	`"all"`, `"indexing"`, or `"viewing"` (default: `"all"`)

Response:

{
  "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:

GET /api.php?action=extensionMappings&type=indexing

Returns only indexing mappings with indexing_count.

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.

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:

{
  "success": true,
  "extension": "php",
  "type": "indexing",
  "setting": "index_php",
  "found": true
}

Not found response:

{
  "success": true,
  "extension": "unknownext",
  "type": "indexing",
  "setting": null,
  "found": false
}

Icon Management

List All Icons

Get a complete list of available icon files.

GET /api.php?action=icons

Response:

{
  "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.

GET /api.php?action=icon&name={filename}

Parameters:

Parameter	Type	Required	Description
`name`	string	Yes	Icon filename (e.g., "php.png")

Response:

{
  "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.

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:

{
  "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:

GET /api.php?action=findIcon&type=folder

Get Icon Mappings

Get the complete mapping of extensions to icon filenames.

GET /api.php?action=iconMappings

Response:

{
  "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.

GET /api.php?action=status

Response:

{
  "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.

GET /api.php

Response:

{
  "success": true,
  "service": "Indexer API",
  "version": "1.0",
  "description": "API for the custom indexer project",
  "endpoints": {
    "versionCheck": {
      "url": "?action=versionCheck&current_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.

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.

GET /style/{filename}

Examples:

GET /style/8d9f7fa8de5d3bac302028ab474b30b4.css
GET /style/latin-400.woff2

Configuration Files

Direct access to configuration and mapping files.

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:

{
  "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:

{
  "error": "Extension parameter is required",
  "status": 400
}

Resource Not Found:

{
  "error": "Icon not found",
  "status": 404
}

Invalid Configuration:

{
  "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
function callIndexerAPI($endpoint, $params = []) {
    $baseUrl = 'https://api.indexer.ccls.icu/api.php';
    $url = $baseUrl . '?action=' . $endpoint;
    
    if (!empty($params)) {
        $url .= '&' . http_build_query($params);
    }
    
    $context = stream_context_create([
        'http' => [
            '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

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

Always check for errors in API responses
Implement fallback behavior for failed requests
Cache successful responses to reduce API calls
Log errors appropriately for debugging
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 - Understanding configuration structure
Installation Guide - API integration setup

API Reference

Table of Contents

Overview

API Features

Base URL & Authentication

Base URL

Authentication

Request Headers

Configuration Endpoints

Get Configuration

Version Check

Extension Management

Get Extension Mappings

Get Extension Setting

Icon Management

List All Icons

Get Specific Icon

Find Icon for File Type

Get Icon Mappings

System Information

API Status

API Information

Direct Resource Access

Icon Files

Stylesheets

Configuration Files

Error Handling

Error Response Format

HTTP Status Codes

Common Error Examples

Client Implementation

Caching Strategy

Timeout Recommendations

PHP Example

JavaScript Example

Error Handling Best Practices

Rate Limiting Considerations