Logistika tizimining API (Application Programming Interface) arxitekturasi RESTful standartlariga asoslanishi va xavfsizlik, tezlik hamda masshtablilikni (scalability) ta'minlashi shart.

Quyida tizimning 3 ta asosiy foydalanuvchisi (Mijoz, Kuryer, Admin) uchun mo'ljallangan API endpointlar ro'yxati va Swagger (OpenAPI 3.0) namunasi keltirilgan.

Откроется в новом окне

Shutterstock

Открыть

1. Asosiy API Endpointlar Ro'yxati

Endpointlar funksional vazifasiga ko'ra guruhlarga bo'lingan. Barcha so'rovlar /api/v1 prefiksi bilan boshlanadi.

A. Public & Client (Mijozlar uchun)

Bu qism mobil ilova va veb-sayt foydalanuvchilari uchun.

B. Driver & Courier (Kuryerlar uchun)

Kuryer ilovasi (Driver App) uchun maxsus endpointlar.

C. Admin & Warehouse (Ombor va Boshqaruv)

Bu API lar orqali operatorlar tizimni boshqaradi.

2. Swagger (OpenAPI 3.0) Strukturasi Namunasi

Quyida eng muhim endpoint — Yangi Yuk Yaratish (POST /shipments) uchun Swagger hujjati (YAML formatida) keltirilgan. Bu hujjat orqali frontend dasturchilar backend qanday ishlashini tushunadilar.

YAML

openapi: 3.0.3
info:
  title: Musbat Logistics API
  description: Yuk tashish va yetkazib berish xizmati uchun API
  version: 1.0.0
servers:
  - url: https://api.musbat.uz/v1
    description: Production Server

paths:
  /shipments:
    post:
      summary: Yangi yuk (buyurtma) yaratish
      description: Foydalanuvchi tomonidan yangi yuk yaratiladi va tracking raqam generatsiya qilinadi.
      tags:
        - Shipments
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sender_address
                - receiver_address
                - packages
              properties:
                sender_address:
                  $ref: '#/components/schemas/Address'
                receiver_address:
                  $ref: '#/components/schemas/Address'
                service_type:
                  type: string
                  enum: [STANDARD, EXPRESS, SAME_DAY]
                  default: STANDARD
                packages:
                  type: array
                  items:
                    $ref: '#/components/schemas/PackageItem'
      responses:
        '201':
          description: Yuk muvaffaqiyatli yaratildi
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1024
                  tracking_number:
                    type: string
                    example: "MSB-88329102"
                  label_url:
                    type: string
                    example: "https://api.musbat.uz/v1/shipments/1024/label.pdf"
                  estimated_delivery:
                    type: string
                    format: date-time
                    example: "2026-02-16T14:00:00Z"
        '400':
          description: Ma'lumotlar noto'g'ri kiritildi (Validation Error)
        '401':
          description: Avtorizatsiyadan o'tilmagan

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  
  schemas:
    Address:
      type: object
      properties:
        full_name:
          type: string
          example: "Alisher Valiyev"
        phone:
          type: string
          example: "+998901234567"
        street_line1:
          type: string
          example: "Amir Temur ko'chasi, 15-uy"
        city:
          type: string
          example: "Toshkent"
        zip_code:
          type: string
          example: "100000"
        geo:
          type: object
          properties:
            lat: 
              type: number
              format: float
            lng: 
              type: number
              format: float

    PackageItem:
      type: object
      properties:
        weight_kg:
          type: number
          example: 2.5
        dimensions:
          type: object
          properties:
            length: { type: integer, example: 30 }
            width: { type: integer, example: 20 }
            height: { type: integer, example: 10 }
        description:
          type: string
          example: "Elektronika"

3. Professional Maslahatlar (Best Practices)

1. Idempotency Key:

   POST /shipments kabi to'lov yoki buyurtma yaratish so'rovlarida Header'da Idempotency-Key (masalan, UUID) yuborishni talab qiling. Agar internet uzilib qolsa va mijoz qayta so'rov yuborsa, server bu kalitni tekshirib, ikkinchi marta dublikat buyurtma yaratmaydi.

2. Rate Limiting:

   Public API (/tracking) ga soatiga cheklov qo'ying (masalan, bitta IP dan soatiga 100 ta so'rov), aks holda botlar tizimni "yiqitishi" (DDoS) mumkin.

3. HATEOAS (Hypermedia):

   Javob qaytarganda keyingi mumkin bo'lgan harakatlarni ham qo'shib yuboring.

   Misol: Yuk yaratilganda, javob ichida "cancel_url": "/api/v1/shipments/1024" havolasini ham qaytarish.

4. Versioning:

   Har doim URL da versiyani ko'rsating (/v1/). Kelajakda tizimni tubdan o'zgartirsangiz (/v2/), eski mijozlarning ilovalari buzilib qolmaydi.