backend: design and build the Public REST API v1 with OpenAPI spec

[ShantKhatri]

Summary

Product doc section 5.12 specifies a Public REST API for programmatically creating, updating, and sharing DevCards. Design and implement the versioned public API under /api/v1/ with full OpenAPI 3.1 documentation generated at runtime.

Context

The current backend at apps/backend/src/routes/ serves internal app routes. This task builds a separate, stable, versioned public API surface with API key authentication (distinct from session auth) and machine-readable docs.

Tasks

• design the API key authentication strategy:
  • add ApiKey model to Prisma schema: id, userId, keyHash (bcrypt), label, lastUsed, createdAt, revokedAt.
  • add POST /api/v1/keys (session auth) to create a key — returns the raw key once, never again.
  • add DELETE /api/v1/keys/:id to revoke.
• create a Fastify plugin apps/backend/src/plugins/apiKey.ts that validates Authorization: Bearer <key> on /api/v1/ routes.
• implement v1 endpoints:
  • GET /api/v1/profiles/me — returns authenticated user's full profile.
  • PUT /api/v1/profiles/me/links — add a platform link.
  • DELETE /api/v1/profiles/me/links/:id — remove a link.
  • GET /api/v1/profiles/:username — public profile read.
• register @fastify/swagger and @fastify/swagger-ui to auto-generate OpenAPI spec from route schemas.
• serve the spec at GET /api/v1/openapi.json and UI at /api/v1/docs.
• write integration tests for API key creation, rotation, revocation, and endpoint access.
• add API key management UI stub in web settings page.

Acceptance Criteria

• /api/v1/docs renders a working Swagger UI.
• API keys authenticate correctly and rate-limited separately from session users.
• all v1 endpoints conform to the OpenAPI spec.
• revoking a key immediately returns 401 on next use.

Difficulty

senior — requires auth system design, OpenAPI tooling, Prisma schema evolution, and versioning strategy.

[SdSarthak]

Hi @nowbind,

I'd love to work on this issue under GirlScript Summer of Code 2026.

Designing a versioned public API with API key auth and auto-generated OpenAPI docs is a backend architecture task I'm comfortable with. I have experience with API design, token management, and OpenAPI tooling.

My plan: add the ApiKey Prisma model with hashed storage, build the Fastify apiKey plugin for Bearer validation on /api/v1/ routes, implement the v1 profile endpoints, and wire up @fastify/swagger + @fastify/swagger-ui for the auto-generated spec at /api/v1/docs. I'll also cover key rotation, revocation, and the integration test suite.

Could you please assign this to me?

Thanks!

[Vardhan2006]

Hey @ShantKhatri I would like to work on this issue, could you please assign it to me?

[shivendra0712]

Hi @ShantKhatri, I’d like to work on this issue.

I have experience with Fastify, Prisma, authentication flows, OpenAPI/Swagger integration, and REST API versioning. I can handle the full implementation including:

API key authentication strategy and Prisma schema updates
Secure key generation, hashing, rotation, and revocation
Fastify API key plugin for /api/v1/*
Public v1 REST endpoints
OpenAPI 3.1 documentation with Swagger UI
Integration tests for auth and endpoint access
API key management UI stub in settings

I’ll ensure the API remains versioned, well-documented, and backward-compatible, with proper separation between session auth and API key auth.

Please assign this issue to me.

[ShantKhatri]

Hi @nowbind,

I'd love to work on this issue under GirlScript Summer of Code 2026.

Designing a versioned public API with API key auth and auto-generated OpenAPI docs is a backend architecture task I'm comfortable with. I have experience with API design, token management, and OpenAPI tooling.

My plan: add the ApiKey Prisma model with hashed storage, build the Fastify apiKey plugin for Bearer validation on /api/v1/ routes, implement the v1 profile endpoints, and wire up @fastify/swagger + @fastify/swagger-ui for the auto-generated spec at /api/v1/docs. I'll also cover key rotation, revocation, and the integration test suite.

Could you please assign this to me?

Thanks!

@SdSarthak Seems automated, not moving further.

[ShantKhatri]

Hey @ShantKhatri I would like to work on this issue, could you please assign it to me?

Warm Welcome. Assigning.

[ShantKhatri]

Hi @ShantKhatri, I’d like to work on this issue.

I have experience with Fastify, Prisma, authentication flows, OpenAPI/Swagger integration, and REST API versioning. I can handle the full implementation including:

API key authentication strategy and Prisma schema updates Secure key generation, hashing, rotation, and revocation Fastify API key plugin for /api/v1/* Public v1 REST endpoints OpenAPI 3.1 documentation with Swagger UI Integration tests for auth and endpoint access API key management UI stub in settings

I’ll ensure the API remains versioned, well-documented, and backward-compatible, with proper separation between session auth and API key auth.

Please assign this issue to me.

Warm Welcome. Assigning. @shivendra0712 and @Vardhan2006 you both guys can collaborate and raise PR accordingly. Happy to help on how collaborated PR raised.

[shivendra0712]

Hi @ShantKhatri ,

Implemented the complete Public REST API v1 with API key authentication, OpenAPI 3.1 docs, Swagger UI, and integration tests as described in issue #38.

Current status:

Backend implementation completed
API key auth and revocation working correctly
Swagger docs available under /api/v1/docs
Integration tests added and passing locally

The only failing check is the Vercel deployment authorization for fork PRs. Please re-run/authorize the Vercel check if required.

Would appreciate a review when available. Thanks!