Meaning
Query parameter versioning appends a version indicator to the URL query string (e.g., ?version=2) to route clients to the correct API implementation. It addresses the pain of evolving an API without breaking existing consumers by letting clients opt into new behavior explicitly. This approach is reached for when teams want versioning without restructuring URL paths or adding new headers.
Primary Function
API versioning
Communicative Purpose
Enables incremental API evolution by letting clients select a version via URL query string, avoiding forced breaking changes.
Pattern
GET /resource?version=N → route to vN handler → return versioned response
Função primária
API versioning
Propósito comunicativo
Enables incremental API evolution by letting clients select a version via URL query string, avoiding forced breaking changes.
Situações de gatilho
REST API design: evolving response shapes without altering URL paths; API gateway routing: dispatching requests to versioned backends based on a query flag; Legacy client support: serving old and new consumers from the same endpoint.
Contextos
REST APIs, HTTP services, API gateways, microservices, public web APIs
Padrão
GET /resource?version=N → route to vN handler → return versioned response
Colocados típicos
- URL path versioning
- header-based versioning
- Accept header versioning
- API gateway routing
- semantic versioning
- deprecation policy
Substituições comuns
- URL path versioning (e.g.
- /v2/resource) — more discoverable but couples version to resource identity
- Header-based versioning (Accept: application/vnd.api.v2+json) — cleaner URLs but harder to test in browsers
- No versioning with backward-compatible evolution — avoids overhead but limits breaking changes
Erros comuns
Forgetting to document the default version — clients omit the parameter and get unexpected behavior; Using query versioning for breaking schema changes without a deprecation window — silently breaks clients that don't update; Treating query parameter as cache key without varying cache by version — serves stale or wrong-version responses from CDN/proxy; Mixing query versioning with path versioning inconsistently — confuses routing logic and client expectations
Similar / contraste
URL path versioning — version embedded in path segment; Header-based versioning — version in Accept or custom header; Media type versioning — version in Content-Type negotiation
Interferências
Coming from GraphQL: may assume schema evolution replaces versioning — GraphQL deprecates fields instead, but REST APIs still need explicit version routing; Coming from SOAP/WSDL: may expect versioning via service contract versioning — REST query versioning is a runtime client choice, not a contract artifact
Família do chunk
- URL path versioning
- header-based versioning
- API deprecation strategy
- semantic versioning
- API gateway routing
Nuance
When NOT to use: avoid for public APIs where caching, SEO, or browser-shareability matter — query strings are often stripped or cached inconsistently; Performance: minimal overhead, but adds a routing branch per request; Boundary: query parameters are easily lost in logging/proxy layers, so version intent may be invisible in traces
Efeito pragmático
Lets teams ship breaking changes behind an opt-in flag, giving clients time to migrate while keeping a single deployable endpoint.
Dica de memória
Like a restaurant menu with a 'spice level' checkbox — same dish, different preparation chosen at order time.
Upgrade path
Header-based versioning or media type versioning for cleaner separation of concerns
Log in to save chunks.