Versioning best practices in Rest API

Introduction

Versioning helps keep your API working well for everyone, even when you make changes. It stops old apps from breaking when you add new features.

You want to add new features without breaking old apps.

You need to fix bugs but keep old behavior for existing users.

You want to support different clients using different API versions.

You plan to improve your API over time safely.

You want to communicate changes clearly to developers.

Syntax

Rest API

GET /api/v1/resource
GET /api/v2/resource

or

GET /api/resource?v=1
GET /api/resource?v=2

or

Accept: application/vnd.example.v1+json
Accept: application/vnd.example.v2+json

Version can be in the URL path, query parameter, or HTTP header.

Choose one method and keep it consistent for your API.

Examples

Version in the URL path is easy to see and use.

Rest API

GET /api/v1/users
GET /api/v2/users

Version as a query parameter keeps URLs clean but requires clients to add the parameter.

Rest API

GET /api/users?v=1
GET /api/users?v=2

Version in the HTTP header keeps URLs clean and allows content negotiation.

Rest API

Accept: application/vnd.example.v1+json
Accept: application/vnd.example.v2+json

Sample Program

This simple Flask app shows two API versions with different messages. Clients can choose which version to call by changing the URL.

Rest API

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/api/v1/greet')
def greet_v1():
    return jsonify({'message': 'Hello from version 1!'})

@app.route('/api/v2/greet')
def greet_v2():
    return jsonify({'message': 'Hello from version 2 with new features!'})

if __name__ == '__main__':
    app.run(debug=True)

Important Notes

Keep old versions working as long as needed to avoid breaking users.

Document each version clearly so developers know what changed.

Use semantic versioning (major.minor) to signal big or small changes.

Summary

Version your API to keep it stable and safe for users.

Use URL path, query, or headers for versioning, but be consistent.

Maintain and document versions to help developers use your API well.