Cum să implementezi versioning pentru un API Python

In this tutorial, you'll learn about Cum să implementezi versioning pentru un API Python. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

Versioning-ul API îți permite să faci modificări breaking fără a afecta clienții existenți. În acest ghid vei învăța trei strategii de versioning: prefix URL, header-e personalizate și content negotiation.

Problema

După lansarea API-ului, trebuie să adaugi modificări care nu sunt compatibile cu versiunea curentă. Clienții existenți încă folosesc vechiul API și nu pot fi forțați să migreze imediat.

Soluția Rapidă

1. Versionare prin prefix URL

from fastapi import APIRouter

v1 = APIRouter(prefix="/api/v1")
v2 = APIRouter(prefix="/api/v2")

@v1.get("/utilizatori")
def utilizatori_v1():
    return [{"id": 1, "nume": "John Doe"}]

@v2.get("/utilizatori")
def utilizatori_v2():
    return [{"id": 1, "nume": "John Doe", "email": "john"@example".com"}]

app = FastAPI()
app.include_router(v1)
app.include_router(v2)

Testare:

curl http://localhost:8000/api/v1/utilizatori
curl http://localhost:8000/api/v2/utilizatori

2. Versionare prin header personalizat

@app.get("/utilizatori")
def utilizatori(api_version: str = Header("1")):
    if api_version == "1":
        return [{"id": 1, "nume": "John"}]
    elif api_version == "2":
        return [{"id": 1, "nume": "John", "email": "john"@example".com"}]
    raise HTTPException(400, "Versiune nesuportata")

curl -H "API-Version: 2" http://localhost:8000/utilizatori

3. Versionare prin Content Negotiation (Accept header)

from fastapi import Request

@app.get("/utilizatori")
def utilizatori(request: Request):
    accept = request.headers.get("Accept", "")
    if "application/vnd.api.v1+json" in accept:
        return [{"id": 1, "nume": "John"}]
    elif "application/vnd.api.v2+json" in accept:
        return [{"id": 1, "nume": "John", "email": "john"@example".com"}]
    return [{"id": 1, "nume": "John"}]

curl -H "Accept: application/vnd.api.v2+json" http://localhost:8000/utilizatori

4. Organizare prin foldere separate

api/
  v1/
    __init__.py
    rute.py
    modele.py
  v2/
    __init__.py
    rute.py
    modele.py
  __init__.py

Prevenție

• Alege o strategie de versioning de la început și menține-o consecvent
• Anunță clienții cu luni înainte de a deprecia o versiune veche
• Folosește header-ele Sunset și Deprecation pentru a semnala versiunile depreciate
• Suportă versiunile vechi minimum 6-12 luni după lansarea celei noi

Greșeli Comune

1. Versionare doar prin query parameter -- ?v=2 poate fi ignorat de cache-uri și proxy-uri
2. Lipsa documentației per versiune -- fiecare versiune ar trebui să aibă propria documentație Swagger
3. Schimbarea formatului response-ului fără warning -- clienții se bazează pe structura existentă
4. Versionare în URL dar nu și în baza de date -- migrarea datelor între versiuni trebuie planificată
5. Păstrarea versiunilor vechi la infinit -- stabilește un termen de viață (EOL) pentru fiecare versiune

Exercițiu Practic

Creează un API cu două versiuni: v1 returnează {nume, pret} pentru produse, v2 adaugă categorie și stoc. Folosește prefix URL și un singur router pe versiune.

FAQ