🚀✨ Add /api/pagelist/versions and /api/pagelist/languages endpoints 🎉📋 (#59521)

Author: heiskr

src/article-api/README.md

@@ -1,7 +1,10 @@
 # Article API
 
 This subject folder contains the code for the Article API endpoints:
+
 - `/api/pagelist`
+- `/api/pagelist/versions`
+- `/api/pagelist/languages`
 - `/api/article/body`
 - `/api/article/meta`
 
@@ -17,7 +20,7 @@ The `/api/article/body` endpoint can serve markdown for both regular articles an
 
 ## How it works
 
-The `/api/article` endpoints return information about a page by `pathname`. 
+The `/api/article` endpoints return information about a page by `pathname`.
 
 `api/article/meta` is highly cached, in JSON format.
 
@@ -28,14 +31,15 @@ For autogenerated pages (REST, GraphQL, webhooks, landing pages, audit logs, etc
 #### Transformers
 
 To add a new transformer for other autogenerated content types:
+
 1. Create a new transformer file implementing the `PageTransformer` interface
 2. Register it in `transformers/index.ts`
-3. Create a template in `templates/` to configure how the transformer will organize the autogenerated content 
+3. Create a template in `templates/` to configure how the transformer will organize the autogenerated content
 4. The transformer will automatically be used by `/api/article/body`
 
 ## How to get help
 
-For internal folks ask in the Docs Engineering slack channel. 
+For internal folks ask in the Docs Engineering slack channel.
 
 For open source folks, please open a discussion in the public repository.
 
@@ -139,6 +143,42 @@ Get metadata about an article.
 
 ---
 
+### GET /api/pagelist/versions
+
+Get all available product versions for the docs site.
+
+**Returns**: (object) - JSON object with version information
+
+**Example**:
+```
+❯ curl -s https://docs.github.com/api/pagelist/versions | jq
+{
+  "versions": ["free-pro-team@latest", "enterprise-cloud@latest", "enterprise-server@3.19", ...],
+  "ghesVersions": ["3.19", "3.18", "3.17", ...],
+  "ghesLatest": "3.19",
+  ...
+}
+```
+
+---
+
+### GET /api/pagelist/languages
+
+Get all available languages for the docs site.
+
+**Returns**: (object) - JSON object with language information
+
+**Example**:
+```
+❯ curl -s https://docs.github.com/api/pagelist/languages | jq
+{
+  "languages": ["en", "es", "ja", "pt", "zh", "ru", "fr", "ko", "de"],
+  "allLanguages": { ... }
+}
+```
+
+---
+
 ### GET /api/pagelist/:lang/:productVersion
 
 A list of pages available for a fully qualified path containing the target language and product version.
@@ -165,34 +205,3 @@ A list of pages available for a fully qualified path containing the target langu
 
 ---
 
-
-## Local Development
-
-### Bootstrap steps
-
-1. Start the dev server:
-   ```bash
-   npm run dev
-   ```
-
-2. Test API endpoints locally:
-   ```bash
-   curl http://localhost:4000/api/article/meta?pathname=/en/get-started
-   curl http://localhost:4000/api/article/body?pathname=/en/get-started
-   curl http://localhost:4000/api/pagelist/en/free-pro-team@latest
-   ```
-
-### Running tests
-
-```bash
-npm run test -- src/article-api/tests
-```
-
-## Ownership
-
-- Team: Docs Engineering
-
-### Known limitations
-- Cache invalidation is manual
-- No built-in rate limiting (uses Fastly instead)
-- Limited API versioning

src/article-api/middleware/pagelist.ts

@@ -8,11 +8,85 @@ import { getLanguageCodeFromPath } from '@/languages/middleware/detect-language'
 import { pagelistValidationMiddleware } from './validation'
 import catchMiddlewareError from '@/observability/middleware/catch-middleware-error'
 import statsd from '@/observability/lib/statsd'
+import { allVersions, allVersionKeys } from '@/versions/lib/all-versions'
+import enterpriseServerReleases from '@/versions/lib/enterprise-server-releases'
+import { languages, languageKeys } from '@/languages/lib/languages'
 
 const router = express.Router()
 
 // pagelistValidationMiddleware is used for every route to normalize the lang and version from the path
 
+/**
+ * Get all available product versions for the docs site.
+ * @route GET /api/pagelist/versions
+ * @returns {object} JSON object with version information
+ * @example
+ * ❯ curl -s https://docs.github.com/api/pagelist/versions | jq
+ * {
+ *   "versions": ["free-pro-team@latest", "enterprise-cloud@latest", "enterprise-server@3.19", ...],
+ *   "ghesVersions": ["3.19", "3.18", "3.17", ...],
+ *   "ghesLatest": "3.19",
+ *   ...
+ * }
+ */
+router.get(
+  '/versions',
+  catchMiddlewareError(async function (req: ExtendedRequest, res: Response) {
+    defaultCacheControl(res)
+
+    const response = {
+      // Simple list of all version strings
+      versions: allVersionKeys,
+      // GHES-specific information
+      ghesVersions: enterpriseServerReleases.supported,
+      ghesLatest: enterpriseServerReleases.latest,
+      ghesLatestStable: enterpriseServerReleases.latestStable,
+      ghesReleaseCandidate: enterpriseServerReleases.releaseCandidate,
+      ghesDeprecated: enterpriseServerReleases.deprecated,
+      // Full version details
+      allVersions,
+    }
+
+    res.json(response)
+  }) as RequestHandler,
+)
+
+/**
+ * Get all available languages for the docs site.
+ * @route GET /api/pagelist/languages
+ * @returns {object} JSON object with language information
+ * @example
+ * ❯ curl -s https://docs.github.com/api/pagelist/languages | jq
+ * {
+ *   "languages": ["en", "es", "ja", "pt", "zh", "ru", "fr", "ko", "de"],
+ *   "allLanguages": { ... }
+ * }
+ */
+router.get(
+  '/languages',
+  catchMiddlewareError(async function (req: ExtendedRequest, res: Response) {
+    defaultCacheControl(res)
+
+    // Remove redirectPatterns from output as they are RegExp objects and not JSON serializable
+    const sanitizedLanguages = Object.fromEntries(
+      Object.entries(languages).map(([code, lang]) => {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { redirectPatterns, ...rest } = lang
+        return [code, rest]
+      }),
+    )
+
+    const response = {
+      // Simple list of language codes
+      languages: languageKeys,
+      // Full language details (without redirectPatterns)
+      allLanguages: sanitizedLanguages,
+    }
+
+    res.json(response)
+  }) as RequestHandler,
+)
+
 // If no version or lang is provided we'll assume english and fpt and redirect there
 router.get(
   '/',

src/article-api/tests/pagelist.ts

@@ -73,3 +73,71 @@ describe('Redirect Tests', () => {
     expect(res.headers.location).toBe('/api/pagelist/en/free-pro-team@latest')
   })
 })
+
+describe('Versions API', () => {
+  test('returns 200 and JSON with version information', async () => {
+    const res = await get('/api/pagelist/versions')
+    expect(res.statusCode).toBe(200)
+    expect(res.headers['content-type']).toMatch(/application\/json/)
+
+    const data = JSON.parse(res.body)
+
+    // Check top-level keys exist
+    expect(data).toHaveProperty('versions')
+    expect(data).toHaveProperty('ghesVersions')
+    expect(data).toHaveProperty('ghesLatest')
+    expect(data).toHaveProperty('ghesLatestStable')
+    expect(data).toHaveProperty('ghesReleaseCandidate')
+    expect(data).toHaveProperty('ghesDeprecated')
+    expect(data).toHaveProperty('allVersions')
+
+    // Versions array should contain expected values
+    expect(Array.isArray(data.versions)).toBe(true)
+    expect(data.versions).toContain('free-pro-team@latest')
+    expect(data.versions).toContain('enterprise-cloud@latest')
+
+    // GHES versions should be an array of version strings
+    expect(Array.isArray(data.ghesVersions)).toBe(true)
+    expect(data.ghesVersions.length).toBeGreaterThan(0)
+    expect(data.ghesVersions[0]).toMatch(/^\d+\.\d+$/)
+
+    // ghesLatest should be a valid version string
+    expect(data.ghesLatest).toMatch(/^\d+\.\d+$/)
+
+    // allVersions should be an object with version details
+    expect(typeof data.allVersions).toBe('object')
+    expect(data.allVersions['free-pro-team@latest']).toHaveProperty('version')
+    expect(data.allVersions['free-pro-team@latest']).toHaveProperty('versionTitle')
+  })
+})
+
+describe('Languages API', () => {
+  test('returns 200 and JSON with language information', async () => {
+    const res = await get('/api/pagelist/languages')
+    expect(res.statusCode).toBe(200)
+    expect(res.headers['content-type']).toMatch(/application\/json/)
+
+    const data = JSON.parse(res.body)
+
+    // Check top-level keys exist
+    expect(data).toHaveProperty('languages')
+    expect(data).toHaveProperty('allLanguages')
+
+    // Languages array should contain expected values
+    expect(Array.isArray(data.languages)).toBe(true)
+    expect(data.languages).toContain('en')
+    expect(data.languages).toContain('ja')
+    expect(data.languages).toContain('es')
+
+    // allLanguages should be an object with language details
+    expect(typeof data.allLanguages).toBe('object')
+    expect(data.allLanguages.en).toHaveProperty('name')
+    expect(data.allLanguages.en).toHaveProperty('code')
+    expect(data.allLanguages.en).toHaveProperty('hreflang')
+    expect(data.allLanguages.en).toHaveProperty('locale')
+    expect(data.allLanguages.en.name).toBe('English')
+
+    // Should not contain redirectPatterns (not JSON serializable)
+    expect(data.allLanguages.ja).not.toHaveProperty('redirectPatterns')
+  })
+})

src/frame/middleware/llms-txt.ts

@@ -56,6 +56,8 @@ function generateBasicLlmsTxt(): string {
 ## Docs Content
 
 - [Page List API](${BASE_API_URL}/en/free-pro-team@latest)
+- [Versions API](${BASE_API_URL}/versions): \`curl "https://docs.github.com/api/pagelist/versions"\`
+- [Languages API](${BASE_API_URL}/languages): \`curl "https://docs.github.com/api/pagelist/languages"\`
 - [Article API](https://docs.github.com/api/article): \`curl "https://docs.github.com/api/article?pathname=/en/get-started/start-your-journey/about-github-and-git"\`
 - [Search API](https://docs.github.com/api/search): \`curl "https://docs.github.com/api/search?query=actions&language=en&version=free-pro-team@latest"\`