Versions API Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
The Versions API (/versions/v1) serves as the central source of truth for FOSSBilling update information. It aggregates release data from GitHub, parses metadata such as minimum PHP requirements, and provides consolidated changelogs for instances to determine update paths.
The service is built using the Hono framework and is designed to be runtime-agnostic, though it is primarily deployed on Cloudflare Workers. It utilizes aggressive caching via KV storage to mitigate GitHub API rate limits and ensure high availability even when upstream services are unreachable.
Sources: README.md:3-12, src/services/versions/v1/README.md:1-5
Core Architecture and Data Flow
The Versions API operates by fetching release data from the FOSSBilling/FOSSBilling repository. It processes GitHub's response into a structured format, extracts asset information (specifically FOSSBilling.zip), and fetches PHP version requirements from composer.json using the GitHub GraphQL API.
Data Acquisition Flow
The following diagram illustrates how the service handles a request, including cache-aside logic and upstream fetching.
PHP Version Extraction logic
For releases prior to version 0.5.0, the system looks for PHP requirements in src/composer.json. For newer releases, it queries the root composer.json. This is handled in a single batch GraphQL query to optimize performance.
Sources: src/services/versions/v1/index.ts:285-288, src/services/versions/v1/index.ts:468-485
Endpoint Reference
Public Endpoints
| Endpoint | Method | Description |
|---|---|---|
/ | GET | Returns a map of all available releases, sorted by semantic version (descending). |
/:version | GET | Returns details for a specific version. Accepts latest as a valid alias. |
/count | GET | Returns the total integer count of available releases. |
/build_changelog/:current | GET | Generates a combined Markdown changelog of all releases newer than the :current version. |
Sources: src/services/versions/v1/index.ts:114-239, src/services/versions/v1/README.md:11-66
Administrative Endpoints
GET /update
Triggers a manual refresh of the KV cache. This endpoint requires Bearer authentication using a token stored in AUTH_KV.
- Authentication:
Authorization: Bearer <UPDATE_TOKEN> - Cache Policy:
no-store
Sources: src/services/versions/v1/index.ts:133-176, test/services/versions/v1/middleware.test.ts:178-190
Middleware and Security
The API implements several layers of middleware to ensure performance, compatibility, and security.
Middleware Stack Sequence
- CORS: All endpoints allow cross-origin requests (
*) to support FOSSBilling installations on various domains. - Caching: Responses are typically cached with
max-age: 86400(24 hours). - ETag: Implemented to support
If-None-Matchheaders, allowing clients to receive304 Not Modifiedresponses for unchanged data. - Trailing Slashes: Automatically redirects paths with trailing slashes (e.g.,
/versions/v1/to/versions/v1) using a 301 redirect.
Sources: src/services/versions/v1/index.ts:80-87, test/services/versions/v1/middleware.test.ts:98-124
Data Models
Release Details Object
The result field in version responses contains objects with the following structure:
| Field | Type | Description |
|---|---|---|
version | string | The semantic version tag (e.g., "0.6.0"). |
released_on | string | ISO 8601 timestamp of the GitHub release publication. |
minimum_php_version | string | Extracted requirement from composer.json. |
download_url | string | Direct link to the FOSSBilling.zip asset. |
size_bytes | number | Size of the download asset in bytes. |
is_prerelease | boolean | Flag indicating if the release is marked as a pre-release on GitHub. |
github_release_id | number | The internal GitHub ID for the release. |
changelog | string | The Markdown body of the GitHub release notes. |
Sources: src/services/versions/v1/index.ts:304-313, src/services/versions/v1/README.md:17-26
Error Handling and Resiliency
The service is designed to handle upstream failures gracefully. If the GitHub API returns an error (rate limiting, downtime, or auth failure) and cached data is available, the service will serve the stale data and include a stale: true flag in the response.
Error Response Schema
{
"result": null,
"error_code": 503,
"message": "Unable to fetch releases...",
"details": {
"http_status": 403,
"error_code": "rate_limit_error"
}
}
Sources: src/services/versions/v1/index.ts:101-112, test/services/versions/v1/errors.test.ts:145-165
Authentication Failure Logic
The /update endpoint validates the Bearer token against the UPDATE_TOKEN in AUTH_KV. It implements an internal cache for this token with a 60-second TTL to reduce KV read operations.
Sources: src/services/versions/v1/index.ts:47-65, test/services/versions/v1/errors.test.ts:85-115
Conclusion
The Versions API provides a robust, cached interface for version management within the FOSSBilling ecosystem. By combining RESTful endpoints for version discovery with a consolidated changelog builder and administrative update triggers, it ensures that distributed FOSSBilling instances can efficiently detect and prepare for system updates.