API Versioning

API versioning means assigning a version to an API and maintaining compatibility between different versions.

Mobile App
    ↓
API Version
    ↓
REST API
    ↓
Database

For example, an API can have version 1 and later introduce version 2.

An API may change over time. Fields may be renamed, response structures may change, or new features may be introduced.

Without versioning, these changes can break applications that still expect the old API behavior.

• Protect existing applications
• Introduce new features
• Change response structures safely
• Support older mobile applications
• Allow gradual migration

Suppose an existing application uses:

GET /api/students.php

The application expects:

{
    "id": 10,
    "name": "Rahul"
}

If the server suddenly changes the response to a completely different structure, the existing mobile application may stop working correctly.

Instead of changing the existing API immediately, create a new version.

/api/v1/students.php

/api/v2/students.php

The old application can continue using version 1 while the new application uses version 2.

One common approach is to include the version number in the URL.

https://example.com/api/v1/students

https://example.com/api/v2/students

This approach is simple and easy to understand.

api/
│
├── v1/
│   ├── students.php
│   ├── login.php
│   └── users.php
│
└── v2/
    ├── students.php
    ├── login.php
    └── users.php

Each version can have its own implementation while sharing common database or helper code when appropriate.

A version 1 endpoint might be:

GET
/api/v1/students.php

It can return a response designed for the original mobile application.

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Rahul"
        }
    ]
}

Version 2 can provide an improved response.

GET
/api/v2/students.php

{
    "success": true,
    "data": [
        {
            "student_id": 1,
            "full_name": "Rahul Kumar",
            "course": "React Native"
        }
    ]
}

The response structure can evolve without immediately changing version 1.

A mobile application can explicitly use a particular API version.

const API_URL =
    "https://example.com/api/v1";

A newer mobile application can use:

const API_URL =
    "https://example.com/api/v2";

Old App
   ↓
API v1

New App
   ↓
API v2

This allows users with older versions of the mobile application to continue working while newer users receive the new API features.

Another approach is to specify the version using a query parameter.

/api/students.php?version=1

/api/students.php?version=2

The server reads the version and chooses the appropriate API behavior.

URL path versioning is often easier for beginners to understand.

An API can also use a request header to indicate the version.

API-Version: 2

The server reads the header and selects the appropriate API behavior.

This keeps the version out of the URL but requires additional client and server configuration.

Some API designs use content negotiation with the Accept header.

Accept:
application/vnd.example.v2+json

The server can use this information to determine which representation the client expects.

With URL-based versioning, the version can be represented directly by the folder structure.

/api/v1/students.php
/api/v2/students.php

Each PHP file can implement the response contract for its specific version.

Different API versions can use the same database.

             MySQL
               ↑
        ┌──────┴──────┐
        ↓             ↓
      API v1        API v2
        ↑             ↑
     Old App       New App

Versioning does not necessarily mean creating a separate database for each API version.

Common database connection code can be shared.

api/
│
├── db.php
│
├── v1/
│   └── students.php
│
└── v2/
    └── students.php

Both versions can include the common connection file.

require_once '../db.php';

The exact relative path depends on the folder structure.

A breaking change is a change that can cause an existing client to stop working correctly.

Examples include:

• Removing a response field
• Renaming a response field
• Changing a field's data type
• Changing authentication requirements
• Changing endpoint behavior

Breaking changes are a common reason for creating a new API version.

Some changes can usually be introduced without creating a new major version.

For example, adding a new optional response field may not break clients that ignore unknown fields.

{
    "id": 10,
    "name": "Rahul",
    "course": "React Native"
}

The exact compatibility impact depends on how clients consume the response.

When an older API version is no longer recommended, it can be marked as deprecated.

v1
 ↓
Deprecated

v2
 ↓
Current Version

Clients should be given enough time and information to migrate to the new version.

v1 Released
     ↓
v2 Released
     ↓
v1 Deprecated
     ↓
Migration Period
     ↓
v1 Retired

The exact retirement process depends on the application's users and business requirements.

Keeping the API base URL in one place makes version changes easier.

const API_BASE_URL =
    "https://example.com/api/v1";

export default API_BASE_URL;

When the application migrates to version 2, the base URL can be updated centrally.

import axios from "axios";

const api =
    axios.create({
        baseURL:
            "https://example.com/api/v1"
    });

const response =
    await api.get(
        "/students.php"
    );

console.log(
    response.data
);

A configured Axios instance can keep the API version in one place.

Postman can be used to test each API version separately.

GET
http://localhost/api/v1/students.php

GET
http://localhost/api/v2/students.php

Compare status codes, response structures, validation, authentication, and other behavior.

Authentication endpoints can also be versioned.

/api/v1/login.php

/api/v2/login.php

If the authentication response or token process changes significantly, a new API version can provide the new contract while preserving the old one for existing clients.

• Changing an existing API without considering old clients.
• Removing fields that old applications still require.
• Creating unnecessary versions for every small change.
• Not documenting version differences.
• Not planning API deprecation.
• Forgetting to test older mobile applications.
• Keeping deprecated versions active forever without a plan.

For a beginner-friendly PHP REST API project, URL-based versioning is easy to understand and implement.

/api/v1/
/api/v2/

Keep common database and utility code reusable while maintaining clear API contracts for each version.

Old Mobile App
       ↓
     API v1
       ↓
Migration
       ↓
New Mobile App
       ↓
     API v2

A migration plan allows users to update their application without requiring every installed version to change at exactly the same time.

Mobile Application
       ↓
Choose API Version
       ↓
/api/v1 or /api/v2
       ↓
PHP REST API
       ↓
Authentication
       ↓
Validation
       ↓
MySQL
       ↓
Version-Specific Response
       ↓
Mobile Application

API versioning allows a REST API to evolve while protecting existing clients. URL-based versioning such as /api/v1/ and /api/v2/ is simple and useful for mobile application projects.

API v1
 ↓
Existing Mobile Apps

API v2
 ↓
New Mobile Apps

A good versioning strategy includes compatibility planning, documentation, testing, migration, and eventual deprecation of old versions.