Extensions API Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
The Extensions API serves as a centralized registry for FOSSBilling modules, themes, and other add-ons. It provides endpoints for listing available extensions, retrieving detailed metadata for specific items, and generating dynamic status badges (e.g., version or license info) for use in documentation and repositories.
Built on the Hono framework, the service is designed to be platform-agnostic while utilizing Cloudflare D1 for persistent storage of extension data. It integrates with the broader FOSSBilling API ecosystem, which includes the Versions Service and Central Alerts.
Sources: README.md:1-15, src/services/extensions/v1/index.ts:1-12
Core Architecture and Data Flow
The Extensions API utilizes a structured data flow that separates route handling, database interaction, and data modeling. Requests are processed through Hono middleware for CORS and trailing slash normalization before reaching specific endpoint handlers.
Data Request Flow
The following diagram illustrates the sequence of operations when a client requests extension data:
API Endpoints Reference
The service exposes several endpoints under the /extensions/v1 base path. All public endpoints support Cross-Origin Resource Sharing (CORS) from any origin.
| Endpoint | Method | Description |
|---|---|---|
/list | GET | Returns a list of all extensions, optionally filtered by type. |
/:id | GET | Returns full metadata for a specific extension by its ID. |
/:id/version | GET | Returns the latest version tag as plain text. |
/:id/badges/:type | GET | Generates an SVG badge for version, license, or PHP requirements. |
Sources: src/services/extensions/v1/index.ts:14-115
Extensions Listing
The /list endpoint allows discovery of extensions. It supports an optional query parameter type (e.g., mod or theme) to filter results. The underlying database logic retrieves extensions and ensures that release information is available for each item.
Sources: src/services/extensions/v1/index.ts:17-29, test/services/extensions/v1/index.test.ts:162-180
Extension Metadata Structure
Extensions are defined by a comprehensive set of fields, many of which are stored as JSON strings in the D1 database and parsed into objects during retrieval.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (e.g., "Example"). |
type | string | Category of extension (e.g., "mod", "theme"). |
author | Object | Includes id, type, name, and url. |
releases | Array | List of release objects containing tag, download_url, and min_fossbilling_version. |
license | Object | Contains license name and optional URL. |
source | Object | Details about the source repository (e.g., GitHub repo path). |
Sources: test/services/extensions/v1/index.test.ts:11-40, src/services/extensions/v1/index.ts:60-70
Badge Generation System
The API includes a dynamic badge generator using the badge-maker library. This allows developers to embed real-time version and license information into their README files.
Badge Logic Flow
The system determines badge content based on the requested type and the latest available release for the specified extension:
The badge endpoint also supports a color query parameter to override the default "blue" (for known types) or "red" (for errors/unknown types) color schemes.
Sources: src/services/extensions/v1/index.ts:31-77, test/services/extensions/v1/index.test.ts:219-255
Database Schema and Persistence
The service relies on a Cloudflare D1 database binding named DB_EXTENSIONS. The database contains fields for raw extension data, which the ExtensionsDatabase class parses into the following internal interfaces:
// From src/services/extensions/v1/interfaces.ts (Inferred from implementation)
interface Extension {
id: string;
type: string;
author: {
name: string;
url: string | null;
};
releases: Release[];
license: {
name: string;
};
version: string;
}
interface Release {
tag: string;
download_url: string;
min_fossbilling_version: string;
}
Sources: src/services/extensions/v1/index.ts:40-60, test/services/extensions/v1/index.test.ts:43-100
Error Handling
The Extensions API implements standardized error responses. If an extension is not found, a 404 status is returned with a JSON error message. Database connection issues or internal logic failures return a 500 Internal Server Error.
- Not Found:
{"error": {"message": "Extension not found"}}(404) - Server Error:
{"error": {"message": "Unable to load extensions"}}(500)
Sources: src/services/extensions/v1/index.ts:23-25, 41-47, 85-91
Conclusion
The Extensions API provides a vital registry for the FOSSBilling ecosystem, enabling automated version checks and dynamic status reporting for third-party additions. By utilizing Cloudflare's edge infrastructure and D1 database, it ensures low-latency access to extension metadata and utility features like dynamic badges.