feat: add get project endpoint under v1-alpha

[epipav]

Summary

Adds the first route in the public API, GET /v1-alpha/projects/{slug}, and turns on the /v1-alpha version it lives under. Development callers use it to learn which values to pass in repos and platform.

{
  "slug": "kubernetes",
  "name": "Kubernetes",
  "repositories": [{ "url": "https://github.com/kubernetes/kubernetes" }],
  "connectedPlatforms": ["github", "git"]
}

• api/src/versions/registry.ts and api/src/versions/v1-alpha/index.ts: register /v1-alpha. Its spec is served at /v1-alpha/openapi.json as 1.0.0-alpha. The docs reference page still renders only /v1, so alpha routes stay unannounced until the closed-alpha allowlist lands.
• api/src/versions/v1-alpha/projects.ts: the route. It makes one projects_list call (slug, details=true), the same call as the Nuxt handler.
• api/src/lib/errors.ts: NotFoundError (404 not_found) and UpstreamUnavailableError (503 upstream_unavailable), in the same style as InvalidDateRangeError. It also takes notFoundHandler from feat: version deprecation and sunset headers #2224's src/errors/not-found.ts, which is deleted: each branch had created a home for error code without seeing the other, and one file gives the error envelope and the promotion-time GoneError a single place to land. The version-bump playbook now points there (review on #2224).
• api/tests/version-lifecycle.test.ts (from feat: version deprecation and sunset headers #2224): the registry case pinned /v1 as the only version. It now expects ['/v1', '/v1-alpha'], neither with lifecycle metadata.

Decisions worth a look

• repositories is a list of { url } objects. The Overviews group will add repo fields here, and objects keep that additive.
• Platform keys drop the -nango suffix and any resulting duplicates, the same way the UI does. Every value is then one a caller can pass straight into platform.
• An unknown slug returns 404. The epic's "unknown slug returns empty data" rule fits the metric endpoints, where an empty series is a valid answer.
• Every Tinybird failure returns 503 upstream_unavailable, and the original error is logged. Without this, Fastify would pass Tinybird's own status to the caller, so a Tinybird 401 would read as the caller's auth failure.
• One onRequest hook in the alpha plugin sets Cache-Control: private, max-age=0 on every /v1-alpha response, errors included (ADR-0013). api/ has no Redis response cache yet. When it lands, this endpoint belongs in the 24h tier.
• Error bodies use Fastify's default shape, with code set, until the error envelope lands.

Testing

• api/tests/project-endpoint.test.ts: runs the real app and Tinybird client, with fetch stubbed at the HTTP boundary. It covers the response body, the pipe call, platform and repo edge cases, the 404, Tinybird 500/401/429, network and non-JSON failures mapping to 503, the cache header on successes and errors, and the /v1-alpha spec (version, Projects tag, field descriptions, kept out of /v1).
• api/tests/openapi-versions.test.ts: the registry now lists ['/v1', '/v1-alpha'].

References

• JIRA: IN-1345, a sub-task of IN-1141 (Endpoints phase 1: Development)
• feat: version deprecation and sunset headers #2224 (IN-1139) and feat: add shared api schemas and period helpers #2230 (IN-1330, adds ProjectSlugParams) are on main and merged into this branch. That merge is what let notFoundHandler move into src/lib/errors.ts and made the registry test expect /v1-alpha.

• main
  • feat: add get project endpoint under v1-alpha 👈
    • feat: add issues resolution endpoint under v1-alpha #2236
    • feat: add contributions outside work hours endpoint under v1-alpha #2237
    • feat: add commit activities endpoint under v1-alpha #2238
    • feat: add active days endpoint under v1-alpha #2239
    • feat: add pull requests endpoint under v1-alpha #2240

[Copilot]

🟡 Changes recommended

The route lacks required authentication and allowlist enforcement, while malformed upstream responses and the alpha specification violate documented response contracts.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds the first /v1-alpha public API endpoint for retrieving project metadata.

Changes:

• Registers /v1-alpha and its OpenAPI specification.
• Adds project lookup, normalization, and upstream error handling.
• Adds comprehensive endpoint and version-registry tests.

File summaries

File	Description
api/src/lib/errors.ts	Adds 404 and 503 API errors.
api/src/versions/registry.ts	Registers /v1-alpha.
api/src/versions/v1-alpha/index.ts	Configures alpha routes and caching headers.
api/src/versions/v1-alpha/projects.ts	Implements project lookup.
api/tests/openapi-versions.test.ts	Updates version registry expectations.
api/tests/project-endpoint.test.ts	Tests endpoint behavior and specification.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 3
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟢 Approval recommended

The endpoint implementation, version isolation, error mapping, caching behavior, and tests are consistent and complete for the stated scope.

Review effort: Balanced
Findings: None

Resolved since last review (3)

• This publishes the alpha data route without authentication or the closed-alpha organization…
• The Tinybird client only checks that data is truthy, so valid JSON with an invalid shape bypasses…
• This hook does not cover /v1-alpha/openapi.json: app.ts:121-125 mounts that route on the parent…

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation matches its stated scope, has comprehensive tests, and all relevant checks pass.

Review effort: Balanced
Findings: None

[gaspergrom]

Traced this against the Nuxt handler (frontend/server/api/project/[slug]/index.ts): same projects_list call, same -nango suffix stripping. Confirmed the deleted not-found.ts has no leftover references and the registry tests match the new /v1-alpha entry. Solid edge case coverage on the error mapping. LGTM.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Unmatched /v1-alpha 404 responses bypass the scoped cache-header hook.

Review effort: Balanced
Findings: None

Previously missed (1)

In code that hasn't changed since last review

Scoped unmatched paths miss required cache header

api/​src/​versions/​v1-alpha/​index.ts:11

Unmatched paths such as /v1-alpha/does-not-exist bypass this plugin's scoped hook and use the root 404 handler, so they lack the cache header required for every response by ADR-0013. Register the shared not-found handler in this scope, as applyLifecycle does for scoped headers, and add an unmatched-path assertion.