Series: Axios Lesson 96

URL Encoding — application/x-www-form-urlencoded bilan ishlash

Axios'da application/x-www-form-urlencoded so'rovlari: OAuth2 token almashinuvi, brauzerning URLSearchParams APIsi, qs kutubxonasi va avtomatik Content-Type sozlamalari.

96-dars

URL Encoding — application/x-www-form-urlencoded bilan ishlash

Biz ko'pincha zamonaviy REST API'lar bilan ishlaganda ma'lumotlarni JSON formatida (application/json) yuborishga odatlanganmiz. Biroq an'anaviy to'lov shlyuzlari (PayPal, Stripe IPN), eski korporativ backend tizimlari hamda eng muhimi — OAuth 2.0 va OpenID Connect (OIDC) autentifikatsiya serverlari (/oauth/token endpointi) ma'lumotlarni faqat va faqat application/x-www-form-urlencoded formatida qabul qilishni qat'iy talab qiladi.


1. application/x-www-form-urlencoded o'zi nima?

Ushbu formatda ma'lumotlar JSON obyekti emas, balki kalit-qiymat juftliklari & belgisi bilan birlashtirilgan uzun satr (string) ko'rinishida yuboriladi:

POST /oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=admin%40site.com&password=Secret123%21

Bu format URL query parametrlariga juda o'xshaydi, ammo u URL manzilida emas, balki HTTP so'rovining tanasida (request body) yuboriladi. Bo'sh joylar, nuqtalar, @ va boshqa maxsus belgilar URL-kodlanadi (masalan: bo'sh joy + yoki %20 ga, @ esa %40 ga aylanadi).

flowchart LR
    A["JavaScript Obyekti\n{ grant_type: 'password', username: 'ali' }"] --> B["URLSearchParams / qs.stringify"]
    B --> C["URL-Encoded Matn\n'grant_type=password&username=ali'"]
    C --> D["Axios So'rovi\nContent-Type: application/x-www-form-urlencoded"]

2. Axios va Sukutdagi Holat (Default Behavior)

Agar siz Axios orqali odatdagi JavaScript obyektini yuborsangiz:

// ❌ XATO: Axios buni avtomatik tarzda application/json deb yuboradi!
await apiClient.post('/oauth/token', {
  grant_type: 'password',
  username: 'admin',
  password: '123',
});

Backend server agar faqat application/x-www-form-urlencoded kutayotgan bo'lsa, JSON formatidagi so'rovni tushunmay, 400 Bad Request yoki 415 Unsupported Media Type xatosini qaytaradi.


3. Amaliyot: URLSearchParams yordamida OAuth2 Token Servisi

Brauzerlarning o'rnatilgan URLSearchParams APIsi ushbu formatdagi ma'lumotlarni tayyorlash uchun eng qulay vositadir.

[!TIP] Axios'ning avtomatizatsiyasi: Axios'ga URLSearchParams obyekti uzatilganda, Axios uning Content-Type sarlavhasini avtomatik ravishda application/x-www-form-urlencoded;charset=utf-8 deb belgilaydi va ma'lumotlarni to'g'ri kodlaydi.

Keling, to'liq tiplashtirilgan OAuth2 autentifikatsiya servisini yozamiz:

// src/services/authService.ts
import axios from 'axios';

export interface TokenRequestPayload {
  grantType: 'password' | 'refresh_token';
  username?: string;
  password?: string;
  refreshToken?: string;
  clientId: string;
}

export interface AuthTokenResponse {
  access_token: string;
  token_type: string;
  expires_in: number;
  refresh_token: string;
}

export const OAuthService = {
  /**
   * OAuth 2.0 serveridan URL-encoded formatda token olish
   */
  getAccessToken: async (payload: TokenRequestPayload): Promise<AuthTokenResponse> => {
    // 1. URLSearchParams yordamida kalit-qiymat ma'lumotlarini to'playmiz
    const params = new URLSearchParams();

    params.append('grant_type', payload.grantType);
    params.append('client_id', payload.clientId);

    if (payload.username) {
      params.append('username', payload.username);
    }
    if (payload.password) {
      params.append('password', payload.password);
    }
    if (payload.refreshToken) {
      params.append('refresh_token', payload.refreshToken);
    }

    // 2. So'rovni yuboramiz
    const response = await axios.post<AuthTokenResponse>(
      'https://auth.mysite.com/oauth/token',
      params,
      {
        headers: {
          // Ko'rsatish tavsiya etiladi (ba'zi qat'iy serverlar uchun)
          'Content-Type': 'application/x-www-form-urlencoded',
        },
        withCredentials: true,
      }
    );

    return response.data;
  },
};

4. Murakkab va Ichma-ich Obyektlar uchun: qs Kutubxonasi

URLSearchParams faqat oddiy (bir darajali) kalit-qiymat juftliklari uchun juda yaxshi ishlaydi. Biroq agar sizda ichma-ich joylashgan murakkab obyektlar yoki massivlar bo'lsa:

const user = {
  filter: { status: 'active', role: 'admin' },
  tags: ['frontend', 'react'],
};

URLSearchParams bularni to'g'ri kodlay olmaydi (obyektni [object Object] qilib yuboradi). Bunday murakkab holatlarda JavaScript olamida standart hisoblangan qs npm kutubxonasidan foydalaniladi:

npm install qs
npm install --save-dev @types/qs
import qs from 'qs';
import { apiClient } from '../api/client';

const payload = {
  client: { id: 'app_123', name: 'Web Dashboard' },
  scopes: ['read', 'write', 'profile'],
};

// Obyektni to'g'ri url-encoded string formatiga o'tkazish:
// Natija: client%5Bid%5D=app_123&client%5Bname%5D=Web%20Dashboard&scopes%5B0%5D=read...
const encodedData = qs.stringify(payload, { arrayFormat: 'brackets' });

const response = await apiClient.post('/oauth/authorize', encodedData, {
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
});

5. JSON vs FormData vs URL-Encoded Taqqoslovi

Mezon application/json multipart/form-data application/x-www-form-urlencoded
Asosiy maqsadi Standart REST API, zamonaviy CRUD Binar fayllar (rasm, video, PDF) yuklash OAuth 2.0 tokenlari, oddiy HTML formalar
Payload shakli JSON matni ({ "name": "Ali" }) Bo'laklar (boundary) bilan ajratilgan binar oqim Parametrlar satri (name=Ali&role=admin)
Fayl yuborish ❌ Mumkin emas (faqat Base64 bilan, noqulay) ✅ Ideal va juda samarali ❌ Mumkin emas
JavaScript vositasi JSON.stringify() / Oddiy Obyekt new FormData() new URLSearchParams() yoki qs.stringify()
Axios'da sozlash Avtomatik (sukut bo'yicha) FormData uzatish (header yozilmaydi) URLSearchParams yoki qs uzatish

Xulosa

Axios orqali application/x-www-form-urlencoded so'rovlarini yuborishda:

  1. Oddiy obyektlar va OAuth2 so'rovlari uchun brauzerning o'rnatilgan URLSearchParams obyektidan foydalanish eng toza yondashuvdir;
  2. Ichma-ich obyektlar va massivlar mavjud bo'lganda qs.stringify() dan foydalanish tavsiya etiladi;
  3. Content-Type: application/x-www-form-urlencoded sarlavhasini aniq belgilash orqali backend bilan 100% moslik ta'minlanadi.