mufassall

Konspekt · Aloqa

API uslublari

12 daq · Boshlang'ich · mufassall.dtwin.uz/uz/l/apis/

← Darsni ochish

Muammo

Ovqat yetkazish ilovasidagi bitta ekran — «Buyurtmalarim» — avval REST, keyin GraphQL bilan, servislar orasida esa gRPC bilan. Har uslub qayerda ortiqcha yoki kam ma'lumot oladi va har API'ga kerak odatlar: cursor bilan sahifalash, versiyalash va idempotentlik kaliti.

Nimani o'rganasiz

  • Over-fetching, under-fetching va ular keltirib chiqaradigan N+1 chaqiruv
  • REST, GraphQL va gRPC: bitta funksiyada har biri nimaga yaxshi
  • OFFSET o'rniga cursor bilan sahifalash, buzadigan o'zgarish o'rniga yangi versiya
  • Takroriy POST'ni xavfsiz qiladigan Idempotency-Key
Yakuniy sahna
15%20%15%

Diagramma kod sifatida

Darsdagi yakuniy sxemani matn ko'rinishida oling va Jira, GitLab, GitHub, Notion yoki hujjatga qo'ying: Mermaid u yerlarda o'zi chiziladi. D2 va PlantUML (Confluence, IntelliJ) uchun alohida variantlar bor.

Mermaid: sxema

flowchart LR
  n_phone(["Telefon ilovasi"])
  n_api["REST API"]
  n_db[("Baza")]
  n_gql["GraphQL server"]
  n_pricing["Narx servisi"]
  n_phone --> n_api
  n_api --> n_db
  n_phone --> n_gql
  n_gql --> n_db
  n_gql --> n_pricing

Mermaid: so'rovlar ketma-ketligi

sequenceDiagram
  participant n_phone as Telefon ilovasi
  participant n_api as REST API
  participant n_gql as GraphQL server
  participant n_db as Baza
  participant n_pricing as Narx servisi
  Note over n_phone,n_api: REST: bitta resurs, bitta URL
  n_phone->>n_api: GET /v1/orders?limit=20 HTTP/1.1
  n_api-->>n_phone: HTTP/1.1 200 OK
  Note over n_phone,n_api: Under-fetching: 1 + 20 chaqiruv
  n_phone->>n_api: phone network log: 21 requests, 2.6 s
  Note over n_phone,n_api: Maydonlarni klient tanlasin
  n_phone->>n_api: GET /v1/orders?limit=20#38;fields=id,status#38;expand=restaurant HTTP/1.1
  n_api-->>n_phone: HTTP/1.1 200 OK
  Note over n_phone,n_gql: GraphQL: so'rovni klient yozadi
  n_phone->>n_gql: POST /graphql HTTP/1.1
  n_gql-->>n_phone: HTTP/1.1 200 OK
  Note over n_gql,n_db: N+1 serverga ko'chdi
  n_gql->>n_db: SELECT * FROM orders WHERE user_id = 'u_42' LIMIT 20#59;
  Note over n_gql,n_db: ID'larni yig'ib, bir marta so'ra
  n_gql->>n_db: SELECT id, name FROM restaurants
  n_db-->>n_gql: 14 rows
  Note over n_gql,n_pricing: Servislar orasida gRPC
  n_gql->>n_pricing: POST /pricing.v1.Pricing/Quote HTTP/2
  n_pricing-->>n_gql: HTTP/2 200
  Note over n_api,n_db: 2-sahifa 1-sahifani takrorlaydi
  n_api->>n_db: SELECT id, created_at FROM orders
  n_db-->>n_api: ord_962 #124; 2026-11-17 18:02
  Note over n_phone,n_api: /v2 da cursor bilan sahifalash
  n_phone->>n_api: GET /v2/orders?limit=20#38;after=c_ord_962 HTTP/1.1
  n_api-->>n_phone: HTTP/1.1 200 OK
  Note over n_phone,n_api: Qayta urinish ikkinchi buyurtma beradi
  n_phone-xn_api: POST /v1/orders HTTP/1.1
  Note over n_phone,n_api: Idempotency-Key: takrorga o'sha javob
  n_phone->>n_api: POST /v1/orders HTTP/1.1
  n_api-->>n_phone: HTTP/1.1 201 Created

D2

direction: right

n_phone: "Telefon ilovasi" {
  shape: rectangle
}
n_api: "REST API" {
  shape: rectangle
}
n_db: "Baza" {
  shape: cylinder
}
n_gql: "GraphQL server" {
  shape: rectangle
}
n_pricing: "Narx servisi" {
  shape: rectangle
}

n_phone -> n_api
n_api -> n_db
n_phone -> n_gql
n_gql -> n_db
n_gql -> n_pricing

PlantUML: so'rovlar ketma-ketligi

@startuml
participant "Telefon ilovasi" as n_phone
participant "REST API" as n_api
participant "GraphQL server" as n_gql
database "Baza" as n_db
participant "Narx servisi" as n_pricing
note over n_phone, n_api : REST: bitta resurs, bitta URL
n_phone -> n_api : GET /v1/orders?limit=20 HTTP/1.1
n_api --> n_phone : HTTP/1.1 200 OK
note over n_phone, n_api : Under-fetching: 1 + 20 chaqiruv
n_phone -> n_api : phone network log: 21 requests, 2.6 s
note over n_phone, n_api : Maydonlarni klient tanlasin
n_phone -> n_api : GET /v1/orders?limit=20&fields=id,status&expand=restaurant HTTP/1.1
n_api --> n_phone : HTTP/1.1 200 OK
note over n_phone, n_gql : GraphQL: so'rovni klient yozadi
n_phone -> n_gql : POST /graphql HTTP/1.1
n_gql --> n_phone : HTTP/1.1 200 OK
note over n_gql, n_db : N+1 serverga ko'chdi
n_gql -> n_db : SELECT * FROM orders WHERE user_id = 'u_42' LIMIT 20;
note over n_gql, n_db : ID'larni yig'ib, bir marta so'ra
n_gql -> n_db : SELECT id, name FROM restaurants
n_db --> n_gql : 14 rows
note over n_gql, n_pricing : Servislar orasida gRPC
n_gql -> n_pricing : POST /pricing.v1.Pricing/Quote HTTP/2
n_pricing --> n_gql : HTTP/2 200
note over n_api, n_db : 2-sahifa 1-sahifani takrorlaydi
n_api -> n_db : SELECT id, created_at FROM orders
n_db --> n_api : ord_962 | 2026-11-17 18:02
note over n_phone, n_api : /v2 da cursor bilan sahifalash
n_phone -> n_api : GET /v2/orders?limit=20&after=c_ord_962 HTTP/1.1
n_api --> n_phone : HTTP/1.1 200 OK
note over n_phone, n_api : Qayta urinish ikkinchi buyurtma beradi
n_phone ->x n_api : [yo'qoldi] POST /v1/orders HTTP/1.1
note over n_phone, n_api : Idempotency-Key: takrorga o'sha javob
n_phone -> n_api : POST /v1/orders HTTP/1.1
n_api --> n_phone : HTTP/1.1 201 Created
@enduml

PlantUML: komponentlar

@startuml
left to right direction
agent "Telefon ilovasi" as n_phone
component "REST API" as n_api
database "Baza" as n_db
component "GraphQL server" as n_gql
component "Narx servisi" as n_pricing
n_phone --> n_api
n_api --> n_db
n_phone --> n_gql
n_gql --> n_db
n_gql --> n_pricing
@enduml

Xulosa

API uchun besh odat.

1) REST sodda va yaxshi keshlanadi, lekin N+1 va semiz javoblarga qarang. 2) GraphQL tanlovni klientga beradi, lekin resolver'larni guruhlang va so'rov narxini cheklang. 3) gRPC o'z servislaringiz orasidagi chaqiruvlarga mos. 4) Cursor bilan sahifalang, buzadigan o'zgarishni yangi versiya qilib chiqaring. 5) Biror narsa yaratadigan har POST Idempotency-Key qabul qiladi.

Ko'rsatkichlar: boshida va oxirida

Ko'rsatkichBoshidaOxirida
Ekranga chaqiruv11
Ekran yuklanishi180 ms210 ms
Ekranga ma'lumot0,1 MB0,0 MB
Ikki marta buyurtma0/kun0/kun

Qadamlar

  1. Holat REST: bitta resurs, bitta URL

    «Buyurtmalarim» ekraniga oxirgi 20 buyurtmaning har biri uchun holati va restoran nomi kerak.

  2. Muammo Under-fetching: 1 + 20 chaqiruv

    Nom yo'q, shuning uchun ilova har restoranni alohida so'raydi: ro'yxat uchun bitta chaqiruv va yana yigirmata, har buyurtmaga bittadan.

  3. Yechim Maydonlarni klient tanlasin

    REST API ikki parametrni o'rganadi: fields nima qaytarishni sanaydi, expand bog'liq obyektni ichiga joylaydi.

  4. Holat GraphQL: so'rovni klient yozadi

    GraphQL server barcha ma'lumotni bitta tiplangan sxema sifatida tasvirlaydi.

  5. Muammo N+1 serverga ko'chdi

    Telefon bitta chaqiruv qiladi, lekin GraphQL server restaurant'ni har buyurtma uchun alohida topadi.

  6. Yechim ID'larni yig'ib, bir marta so'ra

    Server endi so'rovga kerak barcha restoran ID'larini yig'adi va bazadan IN (...) bilan bir marta so'raydi.

  7. Holat Servislar orasida gRPC

    Ekran narx servisidan yetkazish narxi va vaqtini ham ko'rsatadi.

  8. Muammo 2-sahifa 1-sahifani takrorlaydi

    Eski buyurtmalar aylantirganda OFFSET 20 bilan yuklanadi.

  9. Yechim /v2 da cursor bilan sahifalash

    Sahifa endi nechta qatorni o'tkazishni emas, qayerda tugaganini aytadi: «shu buyurtmadan keyingi 20 tasini ber».

  10. Muammo Qayta urinish ikkinchi buyurtma beradi

    Foydalanuvchi «Buyurtma berish»ni bosadi.

  11. Yechim Idempotency-Key: takrorga o'sha javob

    Birinchi urinishdan oldin ilova tasodifiy kalit yaratadi va uni shu buyurtmaning har takrori bilan yuboradi.

  12. Xulosa Xulosa

    API uchun besh odat.

Atamalar

REST
Har resursga bitta URL va standart HTTP metodlari. Sodda va yaxshi keshlanadi, lekin over-fetching, under-fetching va N+1 chaqiruvlarga olib kelishi mumkin.
GraphQL
Klient qaysi maydonlar kerakligini so'rovning o'zida yozadi va bitta chaqiruvda oladi. N+1 serverga ko'chadi, shuning uchun resolver'lar guruhlanadi va so'rov narxi cheklanadi.
gRPC
Qat'iy sxemali, ikkilik formatdagi tez RPC protokoli. O'z servislaringiz orasidagi ichki chaqiruvlarga mos.
Cursor bilan sahifalash
Keyingi sahifa OFFSET bilan emas, oxirgi ko'rilgan yozuvni bildiruvchi cursor bilan so'raladi. Yangi yozuvlar qo'shilsa ham sahifalar takrorlanmaydi va o'tkazib yuborilmaydi.
Idempotency-Key
Klient har yaratish so'roviga qo'shadigan noyob kalit. Server kalitni saqlaydi va takroriy so'rovga yangi buyurtma yaratmasdan o'sha javobni qaytaradi.