Series: Axios Lesson 107

API Versioning — Turli API versiyalarini boshqarish

Axios orqali turli API versiyalarini (v1, v2, v3) boshqarish: URI Path versioning, Header-based content negotiation, alohida versiya instansiyalari va bosqichma-bosqich migratsiya strategiyalari.

107-dars

API Versioning — Turli API versiyalarini boshqarish

Loyiha rivojlanib borgan sari backend jamoasi eski ma'lumotlar strukturasini o'zgartirmasdan, yangi va tezkor imkoniyatlarga ega bo'lgan yangi API versiyalarini (v2, v3) ishlab chiqishiga to'g'ri keladi.

Katta tizimlarda eski kodlarni bir kechada yangi versiyaga to'liq ko'chirish (big-bang migration) juda xavflidir. Frontend ilovasi bir vaqtning o'zida ham eski (v1), ham yangi (v2) API versiyalaridan xavfsiz va bosqichma-bosqich foydalana olishi kerak.


1. API Versiyalashning 3 Ta Asosiy Strategiyasi

Sanoatda API versiyalarini uzatishning asosan uchta usuli qo'llaniladi:

flowchart TD
    A["API Versiyalash Strategiyalari"] --> B["1. URI Path Versioning\nhttps://api.site.com/v1/users\nhttps://api.site.com/v2/users"]
    A --> C["2. Header-based Versioning\nAccept: application/vnd.myapi.v2+json\nX-API-Version: 2"]
    A --> D["3. Query Parameter Versioning\nhttps://api.site.com/users?v=2"]
  1. URI Path Versioning (Eng keng tarqalgan): Versiya to'g'ridan-to'g'ri URL manzilining boshida ko'rsatiladi (/api/v1/users va /api/v2/users). Bu usul tushunarli va keshirlash uchun juda qulay.
  2. Header-based Versioning (Content Negotiation): URL o'zgarmaydi, ammo HTTP sarlavhasida maxsus versiya ko'rsatiladi (Accept: application/vnd.mysite.v2+json).
  3. Query Parameter Versioning: Versiya so'rov oxirida parametr sifatida uzatiladi (/api/users?version=2).

2. Amaliyot: URL Path Versioning va Ko'p Instansiyali Arxitektura

Agar loyihada bir vaqtning o'zida ham v1, ham v2 ishlatilishi kerak bo'lsa, har bir versiya uchun baseURL parametri moslashtirilgan alohida Axios instansiyalarini yaratish eng xavfsiz yo'ldir:

// src/shared/api/v1Client.ts
import axios, { AxiosInstance } from 'axios';

export const apiClientV1: AxiosInstance = axios.create({
  baseURL: import.meta.env.VITE_API_V1_URL || 'https://api.mysite.com/v1',
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json',
  },
});
// src/shared/api/v2Client.ts
import axios, { AxiosInstance, InternalAxiosRequestConfig } from 'axios';

export const apiClientV2: AxiosInstance = axios.create({
  baseURL: import.meta.env.VITE_API_V2_URL || 'https://api.mysite.com/v2',
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json',
    'X-Client-Version': '2.0.0', // V2 uchun maxsus versiya sarlavhasi
  },
});

// V2 uchun takomillashtirilgan Bearer token interceptori
apiClientV2.interceptors.request.use((config: InternalAxiosRequestConfig) => {
  const token = localStorage.getItem('access_token');
  if (token && config.headers) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

3. Feature Servislarda Ishlatish va Bosqichma-Bosqich Migratsiya

Tasavvur qiling, eski v1 da foydalanuvchilar oddiy massiv bo'lib kelar edi, yangi v2 da esa optimallashtirilgan paginatsiya va metadata bilan kelmoqda:

// src/features/users/api/users.types.ts

// V1 eski modeli
export interface UserV1 {
  id: string;
  name: string;
  email: string;
}

// V2 yangilangan modeli
export interface UserV2 {
  id: string;
  fullName: string; // 'name' o'rniga 'fullName'
  email: string;
  roles: string[];
}

export interface PaginatedResponse<T> {
  data: T[];
  meta: {
    currentPage: number;
    totalPages: number;
    totalItems: number;
  };
}
// src/features/users/api/users.service.ts
import { apiClientV1 } from '../../../shared/api/v1Client';
import { apiClientV2 } from '../../../shared/api/v2Client';
import { UserV1, UserV2, PaginatedResponse } from './users.types';

export const UsersService = {
  /**
   * Eski v1 endpoint (oddiy ro'yxat)
   */
  getUsersV1: async (): Promise<UserV1[]> => {
    const response = await apiClientV1.get<UserV1[]>('/users');
    return response.data;
  },

  /**
   * Yangi v2 endpoint (paginatsiya va yangi struktura bilan)
   */
  getUsersV2: async (page: number = 1): Promise<PaginatedResponse<UserV2>> => {
    const response = await apiClientV2.get<PaginatedResponse<UserV2>>('/users', {
      params: { page, limit: 10 },
    });
    return response.data;
  },
};

[!TIP] Bosqichma-bosqich yangilash (Gradual Migration): Siz eski sahifalarga teginmasdan, faqat yangi sahifalarda UsersService.getUsersV2() ni ishlatishingiz mumkin. Butun loyiha bir vaqtda buzilish xavfisiz, xotirjam yangilanadi.


4. Header-based Versioning (Muqobil Yondashuv)

Agar backend jamoasi URL yo'lini o'zgartirmasdan, versiyani HTTP Accept sarlavhasi orqali tanishni talab qilsa:

// src/shared/api/client.ts
import axios from 'axios';

export const apiClient = axios.create({
  baseURL: 'https://api.mysite.com',
  headers: {
    // Sukut bo'yicha barcha so'rovlar v1 versiyada ketadi:
    Accept: 'application/vnd.mysite.v1+json',
  },
});

// Kerakli joyda sarlavhani vaqtincha V2 ga o'zgartirib so'rov jo'natish:
export const fetchUsersV2 = async () => {
  const response = await apiClient.get('/users', {
    headers: {
      Accept: 'application/vnd.mysite.v2+json', // V2 talab qilinadi
    },
  });
  return response.data;
};

5. Deprecation & Sunset Sarlavhalarini Kuzatish

Standart RFC 8594 ga ko'ra, zamonaviy backend serverlari eski API endpoint tez orada o'chirilishi haqida Deprecation va Sunset sarlavhalari orqali ogohlantiradi:

Deprecation: @1735689600
Sunset: Wed, 31 Dec 2026 23:59:59 GMT

Axios Response Interceptor yordamida eskirgan endpointlarni avtomatik aniqlash va konsolda ogohlantirish chiqarish mumkin:

// src/shared/api/v1Client.ts
apiClientV1.interceptors.response.use((response) => {
  const deprecation = response.headers['deprecation'];
  const sunset = response.headers['sunset'];

  if (deprecation || sunset) {
    console.warn(
      `[API Warning]: "${response.config.url}" endpointi eskirgan! ` +
        `Ushbu endpoint ${sunset || 'yaqin orada'} butunlay o'chiriladi. V2 ga o'ting.`
    );
  }

  return response;
});

6. Versiyalash Usullari Taqqoslovi

Mezon URI Path (/v1, /v2) Header-based (Accept) Query Param (?v=2)
Ommabopligi ⭐⭐⭐ Juda yuqori ⭐⭐ O'rtacha ⭐ Kam uchraydi
Brauzerda testlash Qulay (URL ochiq ko'rinadi) Qiyin (Header qo'yish kerak) Juda qulay
Axios'da boshqarish Alohida baseURL instansiyalari Header konfiguratsiyasi params: { v: 2 }
Keshirlash (CDN) Juda oson (har xil URL) Murakkab (Vary: Accept) O'rtacha

Xulosa

API versiyalarini to'g'ri boshqarish — frontend arxitekturasining uzoq muddatli barqarorligini ta'minlaydi. URL Path Versioning va alohida Axios instansiyalari (v1Client, v2Client) yordamida yangi funksiyalarni xavfsiz joriy qilish, eski kodlarni asta-sekin yangilash va tizimning to'xtovsiz ishlashini kafolatlash mumkin.