Series: Axios Lesson 50

API Response Typing — API response uchun alohida interface va type'lar

Backend javoblarini tiplashtirish: Envelope (Wrapper) pattern, ApiResponse<T>, PaginatedResponse<T> orqali sahifalangan ma'lumotlarni boshqarish va tiplarni qayta ishlatish.

50-dars

API Response Typing — API response uchun alohida interface va type'lar

Haqiqiy loyihalarda backend ko'pincha to'g'ridan-to'g'ri massiv yoki oddiy obyekt qaytarmaydi. Aksariyat hollarda server ma'lumotlarni maxsus Wrapper (Qobiq / Envelope) obyekt ichida yoki sahifalangan (Pagination) formatda taqdim etadi.

Agar bu tuzilmalarni to'g'ri tiplashtirmasak, kodimizda any yoki tushunarsiz tiplar ko'payib ketadi. Keling, eng ko'p ishlatiladigan ikkita asosiy holatni ko'rib chiqamiz.


1. Standart Wrapper (Envelope) Pattern

Ko'pgina backend arxitekturalari har bir javobni umumiy standart formatda yuboradi:

{
  "success": true,
  "message": "Ma'lumotlar muvaffaqiyatli olib kelindi",
  "data": {
    "id": 1,
    "username": "coder",
    "email": "[email protected]"
  }
}

Bunday holatda har bir obyekt uchun alohida to'liq wrapper interfeysi yozish o'rniga, bitta universal generik ApiResponse<T> qobig'ini yaratamiz:

// 1. Umumiy Wrapper interfeysi (Generic)
export interface ApiResponse<T> {
  success: boolean;
  message: string;
  data: T; // <T> istalgan domen modeli (User, Product va h.k.) bo'lishi mumkin
  errorCode?: string;
}

// 2. Domen modeli
export interface User {
  id: number;
  username: string;
  email: string;
}

Servis qatlamida qo'llanishi:

Endi servis qatlamida ApiResponse<User> yoki ApiResponse<User[]> dan foydalanamiz:

import { ApiWrapper } from '../api/ApiWrapper';
import { ApiResponse, User } from '../types';

export const UserService = {
  getProfile: async (): Promise<User> => {
    // ApiResponse qobig'i bilan javob kelishini ko'rsatamiz
    const response = await ApiWrapper.get<ApiResponse<User>>('/user/profile');
    
    // Bizga faqat sof domen ma'lumoti kerak bo'lgani uchun data qismini qaytaramiz
    return response.data; 
  }
};

2. Sahifalangan javoblar (Paginated Response Typing)

Jadval (Table) yoki cheksiz skroll (Infinite Scroll) bilan ishlaganda server sizga ro'yxat bilan birga sahifalash uchun xizmat qiluvchi qo'shimcha meta-ma'lumotlarni ham qaytaradi (totalCount, currentPage, pageSize va h.k.).

Buning uchun maxsus generik PaginatedResponse<T> interfeysi yaratiladi:

// Sahifalangan javob uchun umumiy interfeys
export interface PaginatedResponse<T> {
  items: T[];           // Asosiy ma'lumotlar massivi (masalan, Article[])
  totalCount: number;   // Jami elementlar soni
  currentPage: number;  // Hozirgi sahifa raqami
  pageSize: number;     // Bir sahifadagi elementlar soni
  totalPages: number;   // Jami sahifalar soni
  hasNextPage: boolean; // Keyingi sahifa mavjudmi?
}

// Domen modeli
export interface Article {
  id: number;
  title: string;
  content: string;
}

Servisda ishlatilishi:

import { ApiWrapper } from '../api/ApiWrapper';
import { PaginatedResponse, Article } from '../types';

export const ArticleService = {
  getPaginatedArticles: async (
    page: number = 1,
    limit: number = 10
  ): Promise<PaginatedResponse<Article>> => {
    // Query params orqali page va limit yuboramiz
    const response = await ApiWrapper.get<PaginatedResponse<Article>>('/articles', {
      params: { page, limit }
    });

    return response; // response to'g'ridan-to'g'ri PaginatedResponse<Article> bo'lib keladi
  }
};

UI Komponentda foydalanish:

import React, { useEffect, useState } from 'react';
import { ArticleService } from '../services/articleService';
import { PaginatedResponse, Article } from '../types';

export const ArticleList = () => {
  const [data, setData] = useState<PaginatedResponse<Article> | null>(null);
  const [page, setPage] = useState<number>(1);

  useEffect(() => {
    ArticleService.getPaginatedArticles(page, 10).then((res) => {
      setData(res);
    });
  }, [page]);

  if (!data) return <div>Yuklanmoqda...</div>;

  return (
    <div>
      <h3>Maqolalar ro'yxati (Jami: {data.totalCount})</h3>
      <ul>
        {data.items.map((art) => (
          <li key={art.id}>{art.title}</li>
        ))}
      </ul>

      <div>
        <button disabled={page <= 1} onClick={() => setPage((p) => p - 1)}>
          Oldingi
        </button>
        <span> {data.currentPage} / {data.totalPages} </span>
        <button disabled={!data.hasNextPage} onClick={() => setPage((p) => p + 1)}>
          Keyingi
        </button>
      </div>
    </div>
  );
};

3. Response strukturalari qiyosiy jadvali

Pattern Foydalanish holati Asosiy maydonlar Afzalligi
Direct Entity (T) Oddiy REST API { id, name, ... } Eng oddiy struktura, qobiqsiz
ApiResponse<T> Standartlashtirilgan backend javobi { success, message, data: T } Barcha javoblar bir xil formatda bo'ladi, xato kodlari aniq
PaginatedResponse<T> Katta hajmli ro'yxatlar, jadvallar { items: T[], totalCount, totalPages, ... } Sahifalashni to'liq tiplashtirish va boshqarish imkoniyati

4. Nima uchun Response Typing'ni alohida ajratish kerak?

  1. Qayta ishlatish imkoniyati (Reusability): ApiResponse<T> va PaginatedResponse<T> kabi generik tiplarni butun loyiha bo'ylab barcha servislar (UserService, ProductService, OrderService va boshqalar) uchun umumiy tarzda ishlatasiz.
  2. Backend o'zgarishlariga moslashuvchanlik: Agar ertaga backend jamoasi javob formatiga yana bitta umumiy maydon qo'shsa (masalan, timestamp yoki requestId), siz uni faqat bitta umumiy interfeysda o'zgartirasiz va u butun ilovada yangilanadi.
  3. UI komponentlarida xavfsizlik: React komponentlarida ma'lumotlarni ekranga chiqarishda data.items, data.totalPages yoki response.success kabi xossalarga murojaat qilganda IDE xato qilishga yo'l qo'ymaydi va to'liq autocomplete beradi.

Xulosa

ApiResponse<T> va PaginatedResponse<T> generiklari real dunyodagi API arxitekturasining asosiy ustunlaridan biridir. Ular backend bilan ma'lumot almashishni standartlashtiradi, UI qatlamida sahifalash va xatoliklarni xavfsiz boshqarishni ta'minlaydi.