There isn’t one. But here are a few options.
Versioning in the URI Path
Essentially the version number
v2 is embedded in the path of the URI itself. Old API versions at the
v2 namespace remain unchanged so as to not break existing clients, and new API features will live at
v4, and so forth.
The most common API versioning pattern, this pattern allows you to make drastic changes to future versions while leaving old APIs as is for backward compatibility.
However, it does mean having separate implementations for each version. Consumers of your API will also need to change their client code when switching between versions.
Versioning with a URI Parameter
Version is embedded in the query parameter
With this pattern, API consumers uses the latest version of the API when the options
v parameter is omitted. However, changes may surprise users who don’t explicitly specify a version number.
Versioning with Content Negotiation
Content Type in the
Accepts header contains a custom MIME type such as
Accept:application/vnd.myapp.v1.user that is used to indicate the API version.
Defined in the HTTP/1.1 Standard, section 14.1, the Accept: header lists the MIME Types of the media that the agent is willing to process.
The benefit is it gives us finer grained versioning to different resources of your API. You can with this approach, return different resource representations on different versions. To a certain extent, we also save some URI changes for your API consumers. However, we do have the added complexity of having to add headers.
Versioning with Request Headers
The API version is specified in a custom Request Header such as
This separates versioning from API call signatures, and it’s not tied to specific resource versions.
Versioning with URI components tend to be easier and is more commonly seen. Recently, more and more APIs are going with Versioning with Content Negotiation and Custom Headers.
Ultimately, you should pick an approach that fits your team and consumers best. Complex versioning gives you more granularity, but is more involved for API consumers/developers.
Regardless of your specific needs and versioning choice, it’s important to start versioning your API from the first public release of your API. You don’t want to break existing clients once your API is already released, to the frustration of your consumers.
📬 Get updates straight to your inbox!
Subscribe to my newsletter to make sure you don't miss anything.