Query Parameter Versioning — Version in the URL Query

In this tutorial, you will learn about Query Parameter Versioning. We cover key concepts, practical examples, and best practices to help you master this topic.

Query parameter versioning specifies the API version as a query parameter, offering the simplest implementation and easiest testing of all versioning strategies.

Request Format

GET /api/users?version=1
GET /api/users?version=2

Implementation

app.get("/api/users", (req, res) => {
  const version = req.query.version || "1";

  if (version === "2") {
    return res.json({ version: "2.0", data: usersV2 });
  }
  return res.json({ version: "1.0", data: usersV1 });
});

Trade-offs

Pros: Easy to test, simple to implement, works in browsers. Cons: Can be forgotten by clients, pollutes query namespace, not RESTful, Caching issues.

Common Mistakes

1. No default version — Clients that forget the parameter get no version.
2. Parameter name conflicts — version might conflict with resource parameters.
3. Caching across versions — Same URL with different versions may be cached incorrectly.

Practice Questions

1. What are the advantages of query parameter versioning?
2. What caching issues arise with this approach?
3. Why might clients forget to include the parameter?

Challenge

Implement query parameter versioning with version as optional parameter. Default to latest version. Test in browser by changing the URL.

What's Next

In the next lesson, you will learn content negotiation versioning.