Do you know how big companies apply versioning in their APIs?

Versioning is essential for ensuring backward compatibility. If your API is used by multiple clients, you should implement a versioning strategy. Let’s examine how major companies apply versioning.

There are many strategies to apply versioning, let’s talk about 4 of them:

• URL path strategy

• Query parameter

• HTTP header 

• Content negotiation

URL path

This is probably the most common strategy. In this situation, we should apply the versioning in the URL path for each resource. For example:

GET https://api.customers.com/v1/customers

In this case, the version (v1) is clearly indicated in the URL, ensuring that clients know exactly which version of the API they are interacting with. This strategy is adopted by many large companies, including GitLab and X (formerly Twitter), to maintain clarity and control over API versioning while evolving their services.

Query parameter

This strategy is less common among Java developers but tends to be more popular with .NET developers. This is largely due to Microsoft's guidelines, which recommend this approach for versioning.

Microsoft used to rely on HTTP headers for versioning, but since the X- prefix for custom headers was deprecated in 2012 with the introduction of RFC 6648, they now recommend using the URL path for versioning. For example,

PUT https://service.azure.com/users/Jeff?api-version=2021-06-04

HTTP header

This strategy is widely adopted by many companies, despite RFC 6648 advising against using custom headers with an X-prefix. For example, Stripe employs versioning through custom headers, as shown in the following code:

curl https://api.stripe.com/v1/charges \
  -u sk_test_QUXcoU3BnbZXp6IMVi7BkW8s: \
  -H "Stripe-Version: 2024-09-30.acacia"

In this case, Stripe uses a custom header (Stripe-Version) to specify the API version, providing flexibility in versioning without altering the URL path.

This strategy is also used by other companies, such as GitHub for example. However, if you would like to use this strategy and do not want to create a custom prefix, you can also use the content negation strategy.

Content negotiation

The content negotiation strategy involves the client and server agreeing on the format and version of the API response through HTTP headers, rather than encoding this information in the URL. This strategy offers flexibility and keeps the URL clean, especially when working with multiple versions of the same API.

For instance, Adidas recommends this strategy by specifying the version in the Accept header, like so:

application/vnd.example.resource+json; version=2

This allows clients to request different versions of the API without altering the URL path, making the interaction more dynamic and adaptable.

The fundamental principle is that you can’t break existing clients, because you don’t know what they implement, and you don’t control them. In doing so, you need to turn a backwards-incompatible change into a compatible one.

– Mark Nottingham

Conclusion

Versioning is essential when maintaining an API that may introduce breaking changes over time!

There are several strategies to handle this, but the key is to choose one and apply it consistently across all your APIs. It's also crucial to minimize breaking changes and prioritize backward compatibility to avoid disrupting clients relying on older versions.

Have you already implemented a versioning strategy for your API?

References

REST API - Gitlab

Microsoft REST API Guidelines

REST API - Stripe

REST API - Adidas