How to Version Your REST API?

May 21, 2026

API Versioning

APIs are not permanent. APIs change as new functionality is added, bugs are resolved, and data structures are modified. Some of these changes may be harmless and integrations can continue to work without code changes. However, some changes may not be so forgiving and would require API clients to make modifications to continue to function. You need a way to handle these changes and their rollouts to prevent API integrations from breaking unexpectedly or with every release. Thankfully, we have API versioning!

Why Do You Need To Version Your API?

If all the changes to your API are backward compatible forever, you will never have a need to version your API. If you're adding new optional properties to a POST request, creating new endpoints and operations, or adding an alternative authentication mechanism, existing API clients will never need to change their code. Things will continue to work as expected.
However, at some point, you will need to add a required field to a POST request, deprecate an endpoint, or force a new authentication mechanism on API clients. As a result, clients will need to update their integration to keep using your API. This problem seems only slightly problematic if you or your direct team are responsible for both the API and its clients. But what if clients are managed by another team? Or by another company as part of a partner program? What if your API is used by hundreds of developers around the world? You are going to need a more structured way to introduce breaking changes to your API. Introduce: API Versioning

API Versioning Is Not Just a Technical Challenge

Before we delve into the technical methods for versioning an API, it's important to callout that API versioning is not just a technical challenge. API versioning is about aligning expectations between stakeholders responsible for the API, and stakeholders responsible for API client integrations. You could version your API however you like, but if it isn't clear how versioning is managed, and how long clients have to move to a newer version before a given API version is sunset, you might as well issue breaking changes whenever you like.
Therefore, as you think about your API versioning strategy, you need to consider the following.

• Setting and communicating your API versioning policy. For example:
• Notifying consumers of major API version changes. Consider how you can contact stakeholders using an API version you are looking to sunset, and notify them as early as possible to give them plenty of time to update client integrations. Consider notifying them regularly so long as their client are on an outdated version.
• Issuing practical timeframes for sunsetting API versions. It should be enough time for client code to be updated, but not so long your team is maintaining a deprecated version of an API for an unreasonable timeframe.

How to Version Your API?

As with most things, there are many ways to version your API. What method you should use depends on your use case.

Path Based Versioning

In this versioning technique, the API's version is embedded in the request path directly such as:

/api/v1/users

Generally, APIs only include the major version in the path. Otherwise, with ever minor update, clients must update all their routes. Internally, depending on how you API's routing is configured, it could be tedious to constantly shift the minor or patch versions of your API with every small change.
With that said, if your API consumers require strict API versioning, and patch or minor version changes can have catastrophic impact on the API integration, you should include them in path versioning. You simply have to be mindful of your API's routing and caching policies.

/api/v1.2.3/users

Path versioning is straightforward for API clients, and internally easy to route when incrementing the version for breaking changes. However, path versioning could encourage API maintainers to accumulate breaking changes in large releases with many modifications rather than introducing small iterative changes to the API. If your API is relatively stable, this shouldn't be an issue. If your API is in active development, you may need to adopt a different versioning technique.

Path Based Versioning in OpenAPI

Thankfully, using the correct `servers` configuration, path versions can quickly be updated in an OpenAPI file. Define your path parameter under your servers such as:

servers:
  - url: https://restlylabs.com/api/v1

Then, when you need to update the path version, you update the server's URL:

servers:
  - url: https://restlylabs.com/api/v2

Benefits of Path Based Versioning

• Very easy for consumers to identify what version they are running on.
• Easy to test and debug; it can be tested easily by submitting a URL in a web browser.
• If you use major versioning in path versioning, it can provide relatively stable URLs for CDN caches. REST idealists may suggest that a URL to a resource must be consistent, but it is more likely a good thing to cache responses based on versions rather than purely the calling resource.
• Very easy to outline in an OpenAPI file.

Drawbacks of Path Based Versioning

• Encourages large breaking releases, especially if the version only includes the major version such as /api/v1/users.
• You have to be mindful of your API's routing configuration as the number of supported versions increase to support path versioning. Effectively, different paths such as /api/v1/users and /api/v2/users could point to the same API handler if there are no breaking changes between version releases, while /api/v1/products and /api/v2/products could point to completely different services.

Query Based Versioning

Query based versioning adds a query parameter to specify the version of the API. For example:

/api/users?version=1.0.0

Query based versioning was introduced to try and have APIs evolve without modifying the URL or introducing more complex methods of API versioning; such as adding a header. Updating the query parameter would modify the underlying API version making it easy for drop-in replacements.
However, query based version didn't stand the test of time for several reasons. Firstly, if the URL grows in length with many query parameters, it becomes difficult to quickly identify what version of the API is being called. For example:

/api/company/1998/user?state=TX&role=IC4&version=1.4.5

In addition, query parameters are used to filter, sort, or modify the API's response; most often used in GET requests. Query based versioning mixes semantics by now supporting response filter and API versioning.

Query Based Versioning in OpenAPI

As of OpenAPI 3.2.0, global parameters are not supported. You can create a parameter component that can be re-used for every path item, but you must make sure to add this parameter to each path.

components:
  parameters:
    ApiVersion:
      in: query
      name: version  
      required: true  
      schema:  
        type: string  
        example: "1.0.0"
paths:
  /users:
    parameters:
      - $ref: "#/components/parameters/ApiVersion"

Benefits of Query Based Versioning

• Easy to implement, easy to route at different stages of an API.
• Easy to test, debug, and update; it can be tested easily by submitting a URL in a web browser.

Drawbacks of Query Based Versioning

• Query parameters are generally used to modify the response data. Query based versioning mixes semantics; is the version parameter filtering the response for a specific version? Or setting the API's version?
• For long paths, or requests with many query parameters, the version may not be as clear.
• It is easy to forget to include during testing and debugging.
• More involved to maintain an OpenAPI spec that uses query based versioning.

Header Versioning

Header versioning adds a custom header that requests a specific API version. For example:

API-Version: 2.0.1

By including the version as a header, hiding it from the URL path, there is more flexibility to include additional labels to the version without bloating the url. For example, the following header version is not bothersome to add:

API-Version: 2.4.1-beta.3+build.20260520.sha9f2c1

However, including it as a path parameter or a query parameter can make reading the URL cumbersome:

/api/2.4.1-beta.3+build.20260520.sha9f2c1/users

/api/users?version=2.4.1-beta.3+build.20260520.sha9f2c1

Since the API version is not as visible as path based versioning or query based versioning, it could be more difficult to debug or develop against depending on the tools used by customers. You may also need to configure additional CORS rules to allow a new custom header to be added, and update your caching configuration to take into account header versioning

Header Based Versioning in OpenAPI

Like query based versions, can create a parameter component that can be re-used for every path item, but you must make sure to add this parameter to each path.

components:
  parameters:
    ApiVersion:
      in: header
      name: API-Version  
      required: true  
      schema:  
        type: string  
        example: "1.0.0"
paths:
  /users:
    parameters:
      - $ref: "#/components/parameters/ApiVersion"

Benefits of Header Based Versioning

• Keeps the path simple and clean, making it easier to include longer version strings.
• Easy to manage routing of different minor API versions based on headers. Set upper and lower version limit boundaries and which handler should manage that version,

Drawbacks of Header Based Versioning

• It can complicate caching since a header must be taken into consideration, and CORS needs to be correctly configured.
• It can be more difficult to try and debug by requiring a header alongside a path to make a successful request.
• Like query based versioning, not as straightforward to describe with OpenAPI as a fixed value.

Date Based Versioning

Date based versioning moves away from semantic versioning and uses a date to determine internally by the API what version to run off of. This is often times set in the header such as:

API-Version: 2026-05-21

Stripe, for example, sets your API version to the date you started with them. Based on the value provided, the API automatically routes you to the correct API version.
This provides elegancy to knowing when the last update to your API client was. When you plan on updating your integration, you can review this value to know when the last update to the integration happened, and set the value to the date of the update for future reference.
This version is very well suited for APIs that are constantly evolving; such as Stripe, once again. You can introduce rolled out changes regularly encouraging small iterations to continuously improve your API.
However, the downside of this approach is it requires a great deal of discipline organizationally and more complex version management by the API. If you have a constantly evolving API, date based versioning can encourage proper versioning hygiene. However, with APIs that don't change frequently or use cases where a strict locking of an API version is required, date based versioning maybe unnecessary.

Date Based Versioning in OpenAPI

Describe date based versions in OpenAPI is the same as header based versions. Describe a component parameter, provide an example, and use that parameter on all paths in the spec.

components:
  parameters:
    ApiVersion:
      in: header
      name: API-Version  
      required: true  
      schema:  
        type: string  
        example: "2026-05-12"
paths:
  /users:
    parameters:
      - $ref: "#/components/parameters/ApiVersion"

Benefits of Date Based Versioning

• Encourages incremental updates to your API instead of large releases.
• API clients don't have to look for specific API versions to integrate with. Dates are easier to understand, and serve as a reference point to know when the last integration update was.
• Easier to establish compatibility guarantees.

Drawbacks of Date Based Versioning

• Requires more organizational discipline in maintaining backward compatibility.
• More complex to manage routing and caching.
• It isn't easy to identify which API version is being requested from the only request information.
• Not as straightforward to outline in an OpenAPI file compared to path based versioning.

Which versioning method should you adopt?

I can easily recommend to not use query based versioning. It sits in an awkward place, blurs the line between parameters that filter responses and sets the API version, and is not elegantly rendered.
Path based versioning is a good time-tested approach for setting an API version. Path based versioning becomes a great option of your API is stable and doesn't change frequently.
If you require some more flexibility in versioning and want to restrict clients to minor and patch version increments, header based versioning can give you that additional flexibility.
Lastly, if your API is a fast evolving product with many planned changes, and long term backward compatibility is a requirement, date based versioning can encourage continuous iteration while simplifying the adoption process for your API customers.

Use Restly to Design Your OpenAPI File

Restly's form based OpenAPI editor makes it easy to design your OpenAPI file with the correct versioning strategy that fits your use case. Sign up for free to try it out.