Laravel API Versioning: All You Need To Know About V1/V2

Have you ever used an external API and specified its version? For example, have you noticed the /v1/ in the URL of https://api.openai.com/v1/models? In this tutorial, I will explain how to use similar versioning for our own APIs we create with Laravel.

In this long tutorial, we will discuss these topics:

• WHY we need versioning?
• How to enable V1 from the beginning
• WHEN to implement V2?
• HOW to implement V2?
• Minor versions like v1.1
• Date-based version numbers
• Versioning with headers

A lot to cover. Let's go!

WHY We Need Versioning? What Problem Does It Solve?

If we take OpenAI, for example, here's the screenshot from their API documentation:

Have you noticed the /v1/ as a part of the URL? That's the version.

That "version 1" means stable methods/parameters/results for everyone who would consume that API version. If they introduce breaking changes for some methods, like renaming parameters or returned result structure, that may be a candidate for a future /v2/.

The same logic applies not only to external APIs. What about Laravel packages? If you use, for example, spatie/laravel-permission version 5, you expect it to work stable, but what if they decide to change some methods? They would likely do that in version 6, right?

Even Laravel itself is a package called laravel/framework. And with each new version, there's an upgrade guide with potential breaking changes, small or big. If any of those changes are introduced in a "minor" 10.x version like 10.x and not 11.0, developers may be unhappy because their code would break.

So, in a broader sense, the word API means the interface, the set of strict rules for the available methods, which would be consumed by API client(s). Without the versioning, it would all be unstable, and the projects on the consumer's side would break with any change in the API.

That's why we need v1, v2, etc. Especially if you don't have any control of the consumers of the API, the most significant example is mobile applications: you can't force everyone always to upgrade apps on their phones, right?

Of course, version numbers could have a different logic, like v1.2.4, or even numbered by the release date, like 2023-04-28.

We will talk about all of that in detail below.

Generally speaking, you may not need API versioning if the only consumer of that API is yourself in your front-end code. Then you can make changes on both the front and back end and make it work. But even then, you never know when the project will expand and needs Android/iOS applications and a bigger team of developers. So the earlier you introduce versioning, the better.

Enable V1 From The Beginning

I recently tweeted this:

The tweet became pretty popular, and I will explain it similarly to you here.

Introducing /v1/ as a part of Laravel API endpoints is pretty straightforward:

Step 1. Prefix all the default...