refactor: add API versioning prefix to backend routes

[snowrugar-beep]

Problem Statement

All backend API routes use bare paths: /gists, /gists/:id, /health. There is no version prefix (e.g., /v1/gists). This means breaking API changes require coordinated deployment of all consumers with no backward compatibility path.

Evidence

• Backend/src/gists/gists.controller.ts — @controller('gists'), no version prefix
• Backend/src/health/health.controller.ts — @controller('health'), no version prefix
• Backend/src/app.controller.ts — @get('health'), no version prefix

Impact

Breaking API changes would break all existing consumers. No support for multiple API versions during migration.

Proposed Solution

1. Add globalPrefix option in main.ts: app.setGlobalPrefix('v1')
2. Update health route to be under /v1 prefix
3. Update any hardcoded frontend API URLs to include /v1/
4. Update E2E tests to use /v1/ prefix
5. Add deprecation header support for future version transitions

Technical Requirements

• Global prefix must not apply to /health if used by load balancer health checks (exclude health route)
• Must use NestJS setGlobalPrefix with exclude() for health routes
• All existing routes must work under /v1/

Acceptance Criteria

1. POST /v1/gists returns 201
2. GET /v1/gists returns 200
3. GET /v1/gists/:id returns 200
4. GET /v1/health returns 200
5. Old routes without /v1/ return 404
6. Frontend API calls use /v1/ prefix
7. All E2E tests pass with new prefix
8. Health route excluded from global prefix for load balancer

File Inventory

• Backend/src/main.ts
• Backend/src/gists/gists.controller.ts
• Backend/src/health/health.controller.ts
• Backend/test/gists.e2e.spec.ts
• Backend/test/app.e2e-spec.ts

Dependencies

None.

Testing Strategy

• E2E tests with and without /v1/ prefix
• Unit tests for route registration

Security Considerations

API versioning enables safer deployments and gradual migration.

Definition of Done

• Global v1 prefix added
• Health route excluded
• Frontend updated
• Tests updated
• All tests passing

[Robinsonchiziterem]

I'm a backend developer with experience building and maintaining versioned REST APIs using NestJS. I’ve worked on implementing API versioning strategies, route prefixing, backward compatibility planning, and updating test suites to support versioned endpoints. I’m comfortable configuring global route prefixes, handling route exclusions for health checks and infrastructure integrations, updating API consumers, and ensuring comprehensive E2E test coverage during API migrations. I would love to work on this issue, my ETA is 1–2 hours.

[grantfox-oss]

🦊 GrantFox — @Robinsonchiziterem has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #23)
2. Your PR will be reviewed by the VertexChainLabs maintainers

Good luck! Track your progress on GrantFox.