Skip to content

Add API versioning strategy guide #24

@PAMulligan

Description

@PAMulligan

Description

Create a guide covering API versioning strategies and how to implement them with Nerva/Hono. The `pipeline.config.json` defines URL-prefix versioning as the default, but users need guidance on the full spectrum of options and when to use each.

Why

API versioning is one of the most debated topics in API design. Nerva takes an opinionated default (URL prefix with `/v1/`), but users need to understand the trade-offs and how to evolve their APIs without breaking consumers.

Acceptance Criteria

  • Create `docs/api-development/api-versioning.md`
  • Cover versioning strategies:
    • URL prefix (`/v1/users`) — Nerva's default
    • Header-based (`Accept: application/vnd.api.v1+json`)
    • Query parameter (`?version=1`)
    • Content negotiation
  • Explain how to implement each in Hono
  • Cover deprecation headers (already in `pipeline.config.json`)
  • Document breaking vs. non-breaking changes
  • Provide a migration checklist for version bumps
  • Reference the `api.versioning` section of `pipeline.config.json`
  • Link from `docs/api-development/README.md`
  • CI passes

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions