Legacy API V1 Assets
Relevant source files
The following files were used as context for generating this wiki page:
Legacy API V1 Assets represent the static documentation infrastructure for CircleCI's original RESTful API. Unlike the dynamic, OpenAPI-driven pipeline used for API V2, the V1 assets consist of a complete, self-contained static site located within the api-v1/ directory. This module ensures that documentation for legacy endpoints remains accessible to users while the platform transitions to newer API versions.
These assets are integrated into the main Antora-based documentation site through a specialized build pipeline. The assets include the primary HTML documentation, associated stylesheets, JavaScript for client-side search and navigation, and various media assets such as fonts and images.
Sources: gulp.d/tasks/build-api-docs.js:5-20, API_DOCS_INTEGRATION.md:9-15
Build and Integration Pipeline
The legacy assets follow a "simple file copying" strategy during the build process. While API V2 requires fetching live specs and generating HTML via Redocly, API V1 is treated as a complete, pre-rendered artifact.
Orchestration Flow
The build process is managed by Gulp and is triggered after the primary Antora site build completes. The pipeline ensures that the directory structure is preserved to maintain relative pathing for internal assets like CSS and JS.
The build script creates the target directory build/api/v1/ if it does not exist and performs a recursive copy of all contents from the source directory. This preserves the static site's integrity, including its internal fonts and images.
Sources: gulp.d/tasks/build-api-docs.js:30-65, API_DOCS_INTEGRATION.md:38-42
Component Architecture
The Legacy API V1 module is comprised of several key sub-directories and files that form a functional documentation portal.
| Component | Path | Description |
|---|---|---|
| Main Document | api-v1/index.html | The primary single-page documentation containing all endpoint references. |
| Stylesheets | api-v1/stylesheets/ | Contains layout and syntax highlighting CSS (e.g., Slate theme). |
| JavaScript | api-v1/javascripts/ | Handles client-side search (Lunr.js), TOC syncing, and language switching. |
| Media | api-v1/fonts/, api-v1/images/ | Static assets including the Slate font family and CircleCI logos. |
Sources: gulp.d/tasks/build-api-docs.js:41-45, API_DOCS_INTEGRATION.md:21-34
Client-Side Logic
The index.html file includes embedded scripts and references to external libraries like jQuery and Lunr.js to provide an interactive experience without a backend. It implements a Table of Contents (TOC) that syncs with the scroll position and a language selector for code snippets.
The search functionality utilizes a local Lunr index that is populated on page load by scanning all h1 and h2 elements in the document.
Sources: api-v1/index.html:1050-1120, TECHNICAL_REFERENCE.md:120-130
API V1 Technical Specification
The documentation describes a RESTful API supporting GET, POST, and DELETE operations. It emphasizes token-based authentication via the Circle-Token header.
Endpoint Categories
The legacy documentation covers several critical resource areas:
- User: Personal account information (
/me). - Projects: Following/unfollowing and listing followed projects.
- Jobs: Triggering, retrying, and canceling job runs.
- Keys: Management of checkout and SSH keys.
- Artifacts: Retrieval of files produced during jobs.
Data Models and Headers
The legacy assets specify specific interaction requirements:
- Authentication: Supports both
Circle-Tokenheader and HTTP Basic Auth (using token as username). - Response Format: Defaults to Clojure EDN unless an
Accept: application/jsonheader is provided. - Rate Limiting: Uses HTTP 429 status codes and the
Retry-Afterheader for throttling.
Sources: api-v1/index.html:640-750, api-v1/index.html:810-850
Navigation and UI Integration
API V1 is integrated into the broader CircleCI documentation site through UI partials. This allows users to switch between the legacy V1 and modern V2 documentation seamlessly.
- Header Dropdown: Implemented in
header-content.hbs, providing direct links to/api/v1/. - Sidebar Links: Integrated into the Antora component explorer, appearing under the "Reference" sections.
- Relative Pathing: Since the assets are copied to
build/api/v1/, they are served at the same level as the main docs, allowing for relative links from standard AsciiDoc pages.
Sources: API_DOCS_INTEGRATION.md:58-75, ARCHITECTURE.md:105-115
Conclusion
The Legacy API V1 Assets module provides a robust mechanism for maintaining backwards compatibility in documentation. By treating the V1 docs as a static collection of assets and utilizing a simplified Gulp-based copy pipeline, the project ensures that documentation for older endpoints remains functional and visually consistent with the legacy Slate theme, even as the primary site architecture moves toward more modern Antora and Redocly standards.
Sources: gulp.d/tasks/build-api-docs.js:140-150, API_DOCS_INTEGRATION.md:145-155