API

Platon Platformasini tashqi resurslar bilan bog'lash uchun chiqariluvchi API-lar to'plami bo'limi

---

API

---

API abbreviaturasi "Application Programming Interface" so'zlarining bosh harflaridan olingan bo'lib, dasturlarni dasturlash interfeysi yoki dastularni dasturiy interfeysi deb tarjima qilinadi. Ko'plab kompaniyalar API'ni tayyor mahsulot sifatida taqdim etishadi. Masalan, Weather Underground metereologik ma'lumotlar olish uchun API sotadi. API so'rovga misol tariqasida quyidagi havolani ko'rib chiqamiz:

http.get("https://e-auksion.uz/api/front/lots")

{
    "totalPages": 193,
    "totalRows": 1927,
    "currentPage": 1,
    "gaming_lots_cnt": 0,
    "rows": [
        {
            "id": 2070118,
            "lot_number": "2070118",
            "name": "Қурилиши тугалланмаган мактаб биноси",
            "full_address": "Ташкентская область, Янгиюльский район, Шўралисой КФЙ, Хўжаобод МФЙ",
            "confiscant_categories_name": "Здания с незавершенным строительством",
            "category_id": 4,
            "start_price": 1.80503E9,
            "zaklad_summa": 9.02515E7,
            "auction_date_str": "20.06.2022 10:00",
            "order_end_time_str": "20.06.2022 09:00",
            "zaklad_percent": 5.0,
        }]
}

API larni kiritishda amal qilinishi kerak bo'lgan parametrlar

API ni qo'shishda quyidagi maydonlar to'ldirilishi kerak:

• path - ushbu maydonda yaratilayotgan API ning nomi kiritiladi. Odatda API ning nomi quyidagi formatda yoziladi v1/yatt/bank, lekin bu ixtiyoriy ravishda yoziladi.
• method - API ning yaratilishida ko'zda tutilgan maqsadga asosan qabul qilish, uzatish va h.k metodlarni kiritish uchun mo'ljallangan (ular GET, POST, PUT, PATCH, DELETE kabilardir).
• auth_handler - API ning avtorizatsiyasi uchun mo'ljallangan maydon bo'lib, o'z ichiga ikki turdagi parametrni qamrab oladi. Bular Bearer Token (JWT token asosida yaratiladi) hamda Basic Auth (API ga so'rov berayotgan user ma'lumotlari aniqlanadi).
• state - Loyihalarga qo'shilgan va biriktirilgan API larning holatini nazorat qilish uchun mo'ljallangan. O'z ichiga active, hidden, archived kabi parametrlarni qamrab oladi.
• access_condition - kimlarga API ga kirishga ruhsat berilishini hal etadi.
• note - API yuzasidan qisqa izoh kiritilishi uchun mo'ljallangan.
• has_transaction - API da ko'zda tutilgan bir nechta parametrlarni tekshirish va xato yuzaga kelsa o'z o'rniga qaytarib qo'yish uchun mo'ljallangan.
• result_cached_seconds - API da qaytishi kerak bo'lgan ma'lumotlarni necha soniyada keshlanishini ko'rsatish uchun mo'ljallangan.
• group_by - API larni guruhlash uchun mo'ljallangan.

API ni loyihalarga qo'shishda method qo'llanilishi bir nechta turga ajratiladi. Bular:

1. GET - ma'lumotlarni qabul qilish uchun mo'ljallangan API larni kiritish nazarda tutiladi.
2. POST - loyihada qo'llanilgan ma'lum forma, menyu, sahifa va h.k larda e'lon qilish uchun mo'ljallangan API lar nazarda tutiladi.
3. PUT - ma'lum bir funksiya yoki protsedura ichida ko'rinishi ko'zda tutilgan kodlarni kiritish uchun mo'ljallangan API larni ishlatish.
4. PATCH - e'lon qilinmasdan kiritilishi ko'zda tutilgan va shu bilan birga yangilash harakati ko'zda tutilgan API lar uchun qo'l keladi.
5. DELETE - Qo'llanilgan funksiyalar ichidagi protsesslarda o'chirilishi nazarda tutilgan amallar uchun foydalanish nazarda tutilgan.

Autentifikatsiya parametrini sozlash maqsadida auth_handler da variant tanlanadi. Bular:

1. Bearer Token - foydalanuvchiga biriktirilgan token orqali autentifikatsiya qilish.
2. Basic Auth - standart bo'yicha biriktirilgan tokenga asosan autentifikatsiya.

Loyihalarga qo'shilgan va biriktirilgan API larning holatini nazorat qilish uchun state maydonining ahamiyati muhim. Chunki uning belgilanganligiga asosan qo'shilgan API ko'rinishi, ko'rinmasligi yoki arxivlanishi mumkin. Uning elementlari quyidagilar:

1. active - ushbu holatda API va uning tashkil etuvchilari funksional jihatdan, qayerda ishlatilgan bo'lsa, to'liq amalga oshiriladi.
2. hidden - agar API ishlashi jihatidan kerak bo'lmasa, uni ushbu holat orqalik o'chirib qo'ysa bo'ladi.
3. archived - ma'lum bir API ni arxivlash uchun qo'llaniladi.

Ma'lum bir API ga kimlarga ruhsat berishni hal etish uchun access_condition maydoni ishlatiladi.

Agar kiritilgan API ga qisqa tushuntirishlar zarur bo'lsa, u holda note maydoniga kerakli bo'lgan asosiy yoki qo'shimcha ma'lumotlar qo'lda kiritiladi.

API da ko'zda tutilgan bir nechta parametrlarni tekshirish va xato yuzaga kelsa o'z o'rniga qaytarib qo'yish mumkin. Buning uchun has_transaction tugmasi bosiladi. Bu asosan bir dona xatolik yuzaga kelsa ham, ma'lumotlarni saqlash uchun as qotadi.

API da qaytishi kerak bo'lgan ma'lumotlarni necha soniyada keshlanishini ko'rsatib o'tish uchun, result_cached_seconds maydonida soniyalar kiritiladi.

Agar mazkur API ni guruhlash kerak bo'lsa, group_by maydonida umumiy guruh nomi kiritib o'tiladi. API larni qanday yaratishni ko'rib chiqdik! Endi ularning tashkil etuvchilari, ya'ni stage larni ko'rib chiqamiz.

Stage maydonlari

---

Quyidagi ketma-ketliklar orqali, yangi API stage qo'shish formasiga o'tiladi:

1. alias - ushbu inputga stagelarining nomi yoziladi.
2. handler - ushbu inputda stagening turi tanlanadi, ya’ni qanday turdagi ma'lumot uzatilishi yoki olinishi kerakligi belgilanadi. Ushbu tanlov selektida qanday turdagi ma'lumot tanlanganligiga qarab, modal oyna ham shakllantiriladi.
3. parent - ushbu inputda stagelarni bir-biriga qaram qilib qo'yish mumkin, ya'ni bir stage ni ikkinchisiga bog'lab qo'yish imkoniyatini beradi.
4. sort order - stagelarni tartiblash imkoniyatini beradi.
5. state - stage ning holatini aks ettiradi. U o'z ichiga bir qator holatlarni qamrab oladi. Ular:
   • archived - faylni to'laligicha arxivga solish uchun
   • hidden - foydalanmaslik uchun holatini noaktiv qilish uchun
   • active - ishlatish uchun soz holatda ekanligini bildirish uchun
6. note - description berish ya'ni statge yuzasidan qisqa ta'rifni kiritish uchun ishlatiladi. Bunda stage ning nima uchun mo'ljallangani hamda uning mohiyati haqida qisqacha ma'lumot kiritish tavsiya etiladi.
7. access_condition - stagening qanday holatda ishlash shartini kiritish uchun mo'ljallangan
8. serialize_result - ushbu input stagedagi ma'lumotlarni tashabbuskorga qaytarish yoki qaytarmasligini ifodalaydi.

Stage ning turlari

---

HTTP Request Handler - bu tur tashqi API ga murojaat qilish uchun ishlatiladi. Bunda:

• method - request turi tanlanish imkoniyatini beradi (GET, POST, PUT, PATCH, DELETE).
• url - API ning manzilini ko'rsatish uchun mo'ljallangan.
• content_type - response turini ko'rsatish uchun mo'ljallangan (application/json, text/plain, text/html, multipart/form-data, application/x-www-form-urlencoded, application/pdf, application/octet-stream).
• body - agar malumotni post qilish kerak bo'lsa, ushbu ma’lumotni shu joyda bayon qilish mumkin.
• headers - auth ma'lumotlarini kiritish uchun mo'ljallangan maydon bo'lib o'z ichiga Key va Value ma'lumotlarini kiritish talab etiladi.

SQL Bulk insert - bu turda ko'plab ma'lumotlarni ya'ni ma'lumotlar listini saqlash imkoniyati mavjud. Bunda:

• sql - ushbu maydonda qaysi jadvalga va qaysi ustunga saqlashni ifodalash uchun postgre sql so'rovlar yoziladi.
• batch_data_source - ushbu stagega kelayotgan list nomi yoziladi #list kabi.

SQL insert - bu tur bitta objectni insert qilish uchun ishlatiladi. Bunda:

• sql - ushbu maydonda qaysi jadvalga va qaysi ustunga saqlashni ifodalash uchun postgresql so'rovlar yoziladi.
• returning_fields - insertdan keyin qaysi ustunidagi ma'lumotni qaytarishni yozib ko'rsatish uchun ishlatiladi.

SQL select - bu tur ma'lumotlarni o'qib olish uchun ishlatiladi. Bunda:

• sql - ushbu maydonda qaysi jadvalga va qaysi ustunga saqlashni ifodalash uchun posgresql so'rovlar yoziladi.
• result_type - ushbu selectda jadvaldan olingan ma'lumotni qanday korinishda kelishi kerakligini nazorat qilish mumkin.

static_json - bu tur asosan ikkita va undan ortiq stagedagi malumotlarni birlashtirish uchun ishlatiladi. Bunda:

• static-json – barcha json formatidagi ma'lumotlar shu yerda yig'iladi.

handler_group - ikki va undan ortiq stagega parent qilib olish va aynan shu stagega shart berish orqali qolganlarini boshqarish mumkin.

joinChildObject - API dagi Objectlar ichida object qurish.

JSEval - bu tur stage ning javascript va java orqali yaratilishi uchun ishlatiladi.

requestDataConvertor

WARNING

? please add info

stageDataConvertor - Stagelardagi ma'lumotlarni boshqa turga convert qilish uchun

Validation - bu tur tizimda qo'llanilishi mumkin bo'lgan validatsiyalar uchun ishlatiladi. Bunda apiga kerakli bo'lgan maydonni tizim ko'rsatmasa (bermasa), berishini sorab 500 xato qaytaradi. Bunda:

• Condition – validatsiya to'g'ri ishlashi uchun shart berish joyi.
• Error_massage – xato haqidagi batafsil ma'lumot kiritish joyi. Bunda xatoni bir nechta tilda kiritish imkoni mavjud.

Quyida siz API'ning ishlash tartibini ko'rishingiz mumkin

Stages

INFO

Platon apida stagelar orqali bita api da ko'plab stagelar yozishimiz mumkin, Handlerlar ketma ketligi orqali, yuqoridagi stage ma'lumotlari esa : orqali ushlanadi, parametrdagi ma'lumotlar esa # beligi orqali ushlanadi.

"API" ro'yxatga olinganidan so'ng uning bosqichlari stages kiritilishi kerak. Stage'lar bu APIga keluvchi so'rovlarning turlaridir. APIga keluvchi so'rovlar GET, POST, PUT, PATCH, DELETE ko'rinishiga ega bo'lishi mumkin.

Handler uchun ishlatiladigan so'rovlar quyidagilardan iborat:

---

SQL Select - bazadan ma'lumotlarni chaqirish uchun ishlatiladi SQL Insert - bazaga ma'lumotni kiritish uchun ishlatiladi SQL Update - bazadagi ma'lumotlarni o'zgartirish uchun ishlatiladi SQL Bulk Insert - bazadagi bir nechta ma'lumotlarni bir vaqtni o'zida kiritish uchun ishlatiladi SQL Batch Update - bazadagi bir nechta ma'lumotlarni bir vaqtni o'zida o'zgartirish uchun ishlatiladi Handler group - Stagelardagi ma'lumotlarni gruxlash Static JSON - Static ma'lumotlarni json shaklida yozish uchun HTTP Request Handler - API ichida boshqa API larga murojaat qilish uchun Joined Child Object - API dagi Objectlar ichida object qurish Validation - Validatsiya qo'yish Stage Data Converter - Stagelardagi ma'lumotlarni boshqa turga convert qilish uchun Request Data Converter - ???? JS Eval - API lar ichida JavaScript kodlar yozish uchun.

Handlerlarning ishlatilishiga namunalar:

---

Quydagi misollar test platonda cars jadvali ustida olib boriladigan ishlar uchun query na'munalar.

• SQL Select

select id,
       car_name,
       car_brand
from cars
where state = 1

Ushbu misolda cars jadvalidagi state = 1 bo'lgan barcha avtomobillar (list ko'rinishida) qaytadi.

Agarda parametr orqali qandaydir ma'lumot orqali querydagi ma'lumotlar saralansa ularni query ichida # belgisi orqali ushlaymiz.

• SQL Insert

insert into cars
    ( id ,
    car_name ,
    car_brand)
values
    (1::integer ,
    #car_name::varchar ,
    #car_brand::varchar)

• SQL Update

update cars
  set car_name = #car_name::varchar
where id = #id::integer

• SQL Bulk Insert - SQL Bulk Insert orqali biz ma'lumotlar omboriga bir nechta ma'lumotlarni list ko'rinishida yuborish uchun ishlatamiz. Masalan, bizda cars nomi array bor va unda bir nechta avtomobillar post qilinadi.

cars = [
  { id: 1, car_name: 'Model S', car_brand: 'Tesla' },
  { id: 2, car_name: 'Civic', car_brand: 'Honda' },
  { id: 3, car_name: 'Mustang', car_brand: 'Ford' },
  { id: 4, car_name: 'Corolla', car_brand: 'Toyota' },
  { id: 5, car_name: 'A4', car_brand: 'Audi' }
];

Agarda biz yuqoridagi cars ga o'xshash list ni yuborish uchun aynan Bulk Insert ishlatamiz. Namuna:

Bu yerda batch_data_source ga kelayotgan array ni # belgisi orqali ushlab olamiz.

Queryda esa quydagicha yoziladi:

insert into cars
      ( id , car_name , car_brand)
values
      (@id ,
       @car_name ,
       @car_brand)

array ichidagi ma'lumotlarni @ belgisi orqali ushlaymiz.

• SQL Batch Update Bu yerda list ko'rinishidagi ma'lumotlar yangilanadi:

Querydagi yozilishi:

update cars
       set car_name = @car_name::varchar
where id = @id::integer

• Handler group - Handler group orqali API lardagi stagelarni guruxlashimiz mumkin, Masalan, APIlarda quydagi stagelar mavjud dep hisoblasak:

va bizda qaysidur APIlarni guruxlash kerak bo'lsa Handler groupdan foydalanamiz.

• Static JSON - Static Json orqali API ga mur'ojaat qilinganda statik bo'lgan ma'lumotlarni json shaklida yoziladi. Masalan:

)

{
  "id":1,
  "name":"test"
}

Va natija PostMan orqali olinganda quydagi natijani olishimiz mumkin.

• HTTP Request Handler - Bu orqali tashqi va boshqa API larga murojaat amalga ochiriladi murojaat qilinadi.

• URL - Murojat qilinishi kerek bo'lgan API URLi. Headersga yuborilayotgan APIning headersda bermoqchi bo'lgan narsalar yoziladi.
• Joined Child Object - Ushbu handler orqali biz API lardan qaytayotgan Objectlar ichida child objectlar qurishimiz mumkin Masalan, bizda API dan quydagi ko'rinishda ma'lumot keladi:

[
        {
            "id": "1",
            "status": 1,
            "car_type": 1,
            "car_name": "BMW X5",
            "car_brand": "BMW"
        },
        {
            "id": "2",
            "status": 1,
            "car_type": 1,
            "car_name": "NEXIA 3",
            "car_brand": "GM-Uzbekistan"
        }
]

Va ushbu holatdagi so'rov esa yuqorida ko'rsatilganidek oddiy select yozilgan:

SQL query esa quyidagicha :

select id,
       status,
       car_type,
       car_name,
       car_brand
from cars
where state = 1

Endi bizga agarda ma'lumotlar boshqa ko'rinishida kerak bo'lsa yani ichma-ich objectlar orqali kerak bo'lsa u holda Joined Child Object oraqli qilamiz, yani:

[
        {
            "id": "1",
            "status": 1,
            "car": {
                "name": "BMW X5",
                "type": 1,
                "brand": "BMW"
            }
        },
        {
            "id": "2",
            "status": 1,
            "car": {
                "name": "NEXIA 3",
                "type": 2,
                "brand": "GM-Uzbekistan"
            }
        }
]

Ko'rinishida kerak bo'lsa

• Alias - Bu yerda object ichidagi child object nomi
• Parent - Qaysi stagedan ma'lumotlar olishi
• Join_prefix - Nima bo'yicha saralab ajratib olishi
• Validation - Validation orqali kelayotgan ma'lumotlarni tekshirishimiz va xato qaytarishimiz mumkin.

• condition orqali shartlarni tekshiriladi
• error_message1 orqali xato qaytganda yuboriluvchi tekst larni yozamiz
• Stage Data Converter Ushbu stage orqali biz boshqa stage ma'lumotlarni convert qilishimiz mumkin.

• Converter ushbu maydonda ma'lumotlarni qaysi turdan qaysi turga conver qilishni tanlanadi.
• Parent ushbu maydon qaysi stagedan ma'lumotlarni olish kerakligi yani ota stage
• Property_name ushbu maydonda qaysi ma'lumotlarni qayta ishlash kerakligini belgilaymiz.
• Request Data Converter
• JS Eval - JS eval orqali API lar ichida JavaScript kodlar yoziladi.

APIda mavjud bosqichlarning ro'yxati APIning havolasiga bosilganda chiqadi

APIga yangi bosqich qo'shish uchun Qo'shish tugmasini bosing va kerakli ma'lumotlarni to'ldiring:

• Bosqich aliasi yani nomlanishi - 1
• Bosqichning turi SQL so'rov, tashqi HTTP so'rov va hokazolar - 2
• Bosqichning so'rov kodi - 3 Barcha ma'lumotlarni kiritgach saqlash - 4 tugmasini bosing

WARNING

E'tibor qarating har bir bosqich turi uchun (Stage handler) o'zgacha qo'shimcha ma'lumotlar qismi mavjud

HTTP Request handler stage

---

API ning ushbu bosqich turida tashqi serverda joylashgan manbaadan api so'rov orqali ma'lumot yuklash uchun foydalaniladi. Qo'shimcha CORS xatoligi (Cross-Origin Resource Sharing)ni oldini olish uchun Request handler bosqichidan foydalaniladi. Misol tariqasida tashqi serverdagi manbaga api so'rov yuboramiz Rasmda:

• Bosqich turi HTTP Request handler - 1
• Bosqichning qaysi tashqi APIga murojaat qilish turi va havolasi - 2
• Bosqichning tashqi API jo'natilayotgan ma'lumot formati - 3
• Bosqichning tashqi API jo'natilayotgan body qismi - 4
• Bosqichning tashqi API jo'natilayotgan header qismi - 5