Skip to content

feat: Introduce API versioning and compatibility headers#61

Open
Glam26 wants to merge 1 commit into
Adamantine-guild:mainfrom
Glam26:feature/api-versioning
Open

feat: Introduce API versioning and compatibility headers#61
Glam26 wants to merge 1 commit into
Adamantine-guild:mainfrom
Glam26:feature/api-versioning

Conversation

@Glam26

@Glam26 Glam26 commented Jun 25, 2026

Copy link
Copy Markdown

I have completed the task. Here's a summary of the changes:

  1. API Versioning & Deprecation Header: I added a global onSend hook in
    Fastify ( apps/access-api/src/app.ts ) that adds the x-guildpass-api-
    version: 1.0.0 header to all API responses. It also surfaces a
    deprecation: true header if a route explicitly marks itself as deprecated
    via its schema definition.
  2. Health Endpoint Output: Updated the GET /health/live endpoint to
    return the current API version ( 1.0.0 ) in its response payload.
    If specified, the client checks the x-guildpass-api-version response
  3. SDK Compatibility Check: Updated GuildPassClientOptions in
    packages/sdk-lite/src/index.ts to accept an optional expectedApiVersion .
    If specified, the client checks the x-guildpass-api-version response
    header and triggers a warning when there is a version mismatch, helping
    integrations identify breaking changes.
  4. Documentation: Added a new "API Versioning & Compatibility" section in
    the README.md to outline the strict compatibility contract for the
    existing /v1 routes and provide explicit guidance on how deprecations
    will be handled in the future.
  5. Testing: Created a new suite of integration tests at apps/access-
    api/test/version.test.ts to verify that the version header is injected
    properly across health endpoints, business routes, and tests that the
    deprecation header is properly surfaced.
  6. Workspace Fixes: Along the way, I resolved several preexisting
    TypeScript and Prisma compilation issues in the MVP (like an unclosed
    Prisma model schema block, improperly configured tsconfig.json
    configurations in test environments, and an unresolved Badge type) which
    were preventing the test suites from cleanly running.

closes #58

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add API versioning and compatibility headers

2 participants