Postman билан API синаш: сўровдан автоматлаштиришгача тўлиқ йўл

Замонавий веб-лойиҳаларнинг деярли барчаси API'лар устига қурилади. Фронтенд сервердан маълумот олади, мобил илова булутга уланади, тўлов тизимлари бир-бири билан сўровлар алмашади. Буларнинг ҳаммаси тўғри ишлаётганига ишонч ҳосил қилиш учун ҳар бир сўровни қўлда браузерда текшириш мумкин эмас. Айнан шу ерда Postman майдонга чиқади. Postman API'ларни синаш, ҳужжатлаш ва автоматлаштириш учун мўлжалланган энг машҳур воситадир ва у оддий GET сўровини юборишдан тортиб бутун бир тест тўпламини CI қувурига улашгача бўлган ишларни қамраб олади.

Ушбу мақолада биз Postman'ни нолдан ўрганамиз. Аввал интерфейс ва асосий сўровлар билан танишамиз, сўнгра коллекция ва муҳитлардан фойдаланиб ишни тартибга соламиз. Кейин JavaScript тест скриптлари ёзиб, API жавобларини автоматик текширишни кўрамиз ва ниҳоят Collection Runner ҳамда Newman ёрдамида бутун тест тўпламини автоматлаштириб, уни доимий интеграция жараёнига қўшамиз. Мақола дастурчилар ва тестерлар учун бир хил даражада фойдали.

Postman нима ва у нима учун керак

Postman — бу HTTP сўровларини қуриш ва юбориш учун график муҳит. Браузер фақат GET сўровларини қулай юборса, Postman POST, PUT, DELETE, PATCH каби барча методларни қўллаб-қувватлайди, header'лар ва body'ни аниқ созлаш имконини беради ҳамда жавобни чиройли форматда кўрсатади. Энг муҳими, Postman ҳар бир сўровни сақлаб, уларни коллекцияларга гуруҳлаб, жамоа билан улашиш имконини беради. Бу API устида ишлаётган жамоа учун ягона ҳақиқат манбаи бўлиб хизмат қилади.

Postman'нинг кучи шундаки, у шунчаки сўров юборувчи эмас. У сизга API ҳужжатларини автоматик яратиш, сохта сервер (mock server) ишга тушириш, мониторинг ўрнатиш ва энг асосийси автоматик тестлар ёзиш имконини беради. Шу сабабли кўп жамоаларда Postman API'нинг бутун ҳаёт циклини бошқарадиган марказий воситага айланади.

Биринчи сўров: GET ва POST

Postman'ни очганингиздан сўнг янги сўров яратасиз, методни танлайсиз ва URL'ни киритасиз. Оддий GET сўрови маълумот олиб келиш учун ишлатилади. Масалан, фойдаланувчилар рўйхатини олиш учун сиз қуйидагича сўров юборасиз ва Postman жавобни JSON кўринишида кўрсатади:

GET https://api.example.com/v1/users
Accept: application/json

# Жавоб:
{
  "data": [
    { "id": 1, "name": "Ali" },
    { "id": 2, "name": "Vali" }
  ]
}

POST сўрови эса серверга янги маълумот юбориш учун ишлатилади. Бунда сиз Body бўлимига ўтиб, raw ва JSON форматини танлайсиз ҳамда юбориладиган маълумотни ёзасиз. Authentication керак бўлса, Authorization бўлимида Bearer Token ёки API Key турини танлайсиз. Қуйидаги мисол янги фойдаланувчи яратишни кўрсатади:

POST https://api.example.com/v1/users
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiI...

{
  "name": "Sardor",
  "email": "sardor@example.com"
}

Коллекция ва муҳит (environment)

Бир нечта сўров билан ишлай бошлаганингизда уларни тартибга солиш зарурати туғилади. Коллекция — бу ўзаро боғлиқ сўровлар тўплами, масалан "Фойдаланувчилар API" ёки "Тўлов API". Коллекциялар сўровларни папкаларга ажратиш, уларга тавсиф ёзиш ва бутун тўпламни бир марта ишга тушириш имконини беради. Бу API'ни тартибли ҳолатда сақлашнинг асосий усули.

Муҳит (environment) эса ўзгарувчилар тўплами бўлиб, у бир хил коллекцияни турли шароитларда ишлатиш имконини беради. Масалан, сизда "dev", "staging" ва "production" муҳитлари бўлиши мумкин ва ҳар бирида URL ҳамда токен бошқача. Сўровларда қаттиқ кодланган қийматлар ўрнига {{base_url}} каби ўзгарувчилардан фойдаланасиз ва муҳитни алмаштирган заҳоти барча сўровлар янги қийматлар билан ишлай бошлайди:

// Муҳит ўзгарувчилари:
base_url = https://api.example.com/v1
token    = eyJhbGciOiJIUzI1NiI...

// Сўровда ишлатиш:
GET {{base_url}}/users
Authorization: Bearer {{token}}

Тест ёзиш: JavaScript скриптлари

Postman'нинг энг кучли томони ҳар бир сўровга тест скриптлари бириктириш имкониятидир. Бу скриптлар JavaScript'да ёзилади ва сўровдан жавоб келгандан кейин автоматик ишга тушади. Тест скриптлари жавобнинг тўғрилигини текширади: статус коди кутилганга мосми, жавоб қанча вақтда келди, body ичида керакли майдонлар борми. Пастдаги мисолда статус коди ва жавоб тузилишини текширувчи оддий тестлар кўрсатилган:

pm.test("Status kodi 200 bo'lsin", function () {
    pm.response.to.have.status(200);
});

pm.test("Javob 500ms dan tez kelsin", function () {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

pm.test("Javobda data massivi bor", function () {
    const json = pm.response.json();
    pm.expect(json.data).to.be.an('array');
    pm.expect(json.data.length).to.be.above(0);
});

Тест скриптлари нафақат текширади, балки кейинги сўровлар учун ўзгарувчиларни сақлай олади. Масалан, login сўровидан келган токен'ни ўзгарувчига сақлаб, кейинги сўровларда ундан фойдаланиш жуда кенг тарқалган амалиётдир. Бу занжирли (chained) сўровлар тузиш имконини беради:

// Login javobidan token'ni olib saqlash:
const json = pm.response.json();
pm.environment.set("token", json.access_token);

// Endi keyingi so'rovlarda {{token}} avtomatik ishlaydi

Автоматлаштириш: Collection Runner ва Newman

Бир нечта сўров ва уларнинг тестлари тайёр бўлгач, уларни бирма-бир қўлда ишга тушириш ўрнига бутун коллекцияни автоматик ишга тушириш мумкин. Collection Runner — бу Postman ичидаги восита бўлиб, у коллекциядаги барча сўровларни кетма-кет юборади ва ҳар бир тестнинг натижасини кўрсатади. Сиз ҳатто CSV файлдан маълумот олиб, битта сўровни турли кирувчи қийматлар билан кўп марта ишга туширишингиз мумкин.

Ҳақиқий автоматлаштириш эса Newman билан бошланади. Newman — бу Postman коллекцияларини буйруқлар қаторида (command line) ишга туширадиган восита. У сизга тестларни ҳар бир код ўзгаришидан кейин автоматик ишга тушириш, яъни доимий интеграция (CI/CD) қувурига улаш имконини беради. Қуйидаги мисол Newman'ни ўрнатиш ва коллекцияни ишга туширишни кўрсатади:

# Newman'ни o'rnatish:
npm install -g newman

# Kolleksiyani muhit bilan ishga tushirish:
newman run users-api.postman_collection.json \
  -e production.postman_environment.json \
  --reporters cli,json

Бу буйруқни GitHub Actions ёки GitLab CI ичига қўйиб, ҳар бир push'дан кейин API тестлари автоматик ишлашини таъминлаш мумкин. Агар бирор тест муваффақиятсиз тугаса, қувур тўхтайди ва жамоа дарҳол хабардор бўлади. Бу API регрессияларини ишлаб чиқаришга чиқишдан олдин тутиб қолишнинг энг ишончли усули.

Mock server ва реал иш жараёни

Баъзан фронтенд жамоаси API тайёр бўлишини кутмасдан ишни бошлаши керак. Postman'нинг mock server имконияти айнан шу вазият учун. Сиз коллекцияга кутилаётган жавобларни намуна сифатида сақлайсиз ва Postman сизга реал API'ни тақлид қилувчи URL беради. Фронтенд бу сохта сервер билан ишлаб тура олади, кейин эса реал API тайёр бўлганда оддийгина URL'ни алмаштирасиз.

Реал иш жараёни одатда қуйидагича кечади: дастурчи янги endpoint ёзади, уни Postman'да қўлда синайди, сўнгра унга тест скриптлари қўшиб коллекцияга сақлайди. Тестер бу коллекцияни кенгайтириб, чегаравий ҳолатларни қоплайди. Ниҳоят бутун коллекция Newman орқали CI қувурига уланади ва ҳар бир релизда автоматик ишлайди. Шундай қилиб Postman битта воситада API'нинг бутун ҳаётини — биринчи сўровдан то автоматлаштирилган регрессия тестларигача — бошқариш имконини беради. Бу нафақат вақтни тежайди, балки API сифатини барқарор сақлайди.