API synagy: Postman/Newman

1) Näme üçin Postman/Newman

• gaýtalanýan regresler we çalt şireler;
• gurşawyň/syrlaryň parametrlenmegi;
• hil ölçegleri we maşyn okalýan hasabatlar.

2) Esasy model

Kolleksiýa - umumy skriptleri bolan soraglar we bukjalar agajy.
Gurşaw - dev/stage/prod (URL, açarlar) üçin '{vars}}' toplumy.
Pre-request script - taýynlyk: gollar, bellikler, maglumatlaryň korelýasiýasy.
Tests - üýtgeýän/artefaktlary tassyklamak we saklamak.
Data-files - Data-driven run üçin CSV/JSON.
Mock/Monitor - gabyklar we döwürleýin barlaglar.

<API v1>
├─ _bootstrap (auth, health, seeds)
├─ Public
├─ Authenticated
│  ├─ Accounts
│  ├─ Payments
│  └─ Reports
└─ _teardown (cleanup)

3) Üýtgeýjiler we syrlar

Üýtgeýjileri aç-açan prefiks diýip atlandyryň: 'baseUrl', 'tenant', 'clientId'.
Syrlary (parollar, client_secret, HMAC-açarlar) CI gurşaw üýtgeýjilerinde saklaň, repozitoriýa jemlemäň.
Satyn alyň: local → collection → environment → globals (iň az mümkin).

json
{
"name": "stage-eu",
"values": [
{"key":"baseUrl","value":"https://api. stage. example. com","type":"text","enabled":true},
{"key":"tenant","value":"eu-1","type":"text","enabled":true}
]
}

4) Tassyklamak: şablonlar

4. 1 OAuth2/OIDC (Client Credentials)

js if (!pm.environment. get("access_token")          Date. now() > pm. environment. get("token_exp")) {
pm. sendRequest({
url: pm. environment. get("authUrl"),
method: 'POST',
header: {'Content-Type':'application/x-www-form-urlencoded'},
body: { mode:'urlencoded', urlencoded:[
{key:'grant_type',value:'client_credentials'},
{key:'client_id',value:pm. environment. get('clientId')},
{key:'client_secret',value:pm. environment. get('clientSecret')},
{key:'scope',value:'payments:read payments:write'}
]}
}, (err, res) => {
pm. environment. set("access_token", res. json(). access_token);
pm. environment. set("token_exp", Date. now()+ (res. json(). expires_in-30)1000);
});
}

Soralanda: 'Authorization: Bearer {{access _ token}}'.

4. 2 HMAC (webhuklar/hyzmatdaşlar)

js const body = pm. request. body? pm. request. body. raw          '': '';
const ts = Math. floor(Date. now()/1000);
const msg = `${ts}.${body}`;
const sig = CryptoJS. HmacSHA256(msg, pm. environment. get('hmacSecret')). toString();
pm. variables. set('ts', ts);
pm. variables. set('sig', sig);

Sözbaşylar: 'X-Timestamp: {{ts}}', 'X-Signature: {{sig}}'.

5) Synaglar: tassyklamalar we korelýasiýa

'pm' ulanyň. expect(...)` и `pm. test("...", fn)`.
"pm" arkaly indiki ädimler üçin kesgitleýjileriňizi saklaň. collectionVariables. set`.

js pm. test("HTTP 200", () => pm. response. to. have. status(200));
pm. test ("Scheme is valid," () => {
const schema = pm. collectionVariables. get("schema_wallet");
pm. expect(tv4. validate(pm. response. json(), JSON. parse(schema))). to. be. true;
});
pm. test ("Contains id," () => {
const id = pm. response. json(). id;
pm. expect(id). to. be. a('string');
pm. collectionVariables. set("wallet_id", id);
});

6) Shemany tassyklamak (OpenAPI/JSON Shema)

JSON Schema-ny üýtgeýän kolleksiýada ýa-da aýratyn faýl bilen saklaň.
OpenAPI üçin: taýýar libalary pre-request/test (ajv, tv4) - 'pm. sendRequest 'raw faýlyna ýa-da JSON lineine.

js pm. collectionVariables. set("schema_wallet", JSON. stringify({
"type":"object",
"required":["id","currency","balance"],
"properties":{
"id":{"type":"string"},
"currency":{"type":"string","pattern":"^[A-Z]{3}$"},
"balance":{"type":"number","minimum":0}
}
}));

7) Data-driven ssenarileri

email, password, currency u1@example. com, P@ss1, EUR u2@example. com, P@ss2, USD

'{{email}}', '{{currency}}' ulanýar.

newman run collection. json -e stage-eu. json -d users. csv

JSON (obýektleriň toplumy) - çylşyrymly ýagdaýlar/gurluşlar üçin amatly.

8) Negatiw ýagdaýlar we durnuklylyk

• 401/403 (belliksiz/nädogry skope/rol).
• 400/422 (shemany tassyklamak, hökmany meýdanlar, çäkler).
• 404 (BOLA/keseki çeşme).
• 409 (gapma-garşylyklar, idempotent açarlary).
• 429 (çäkler) - 'Retry-After' -i barlaň.
• 5xx - müşderiniň dogry pese gaçmagy we retrasy.

js pm. test ("There is Retry-After at 429," () => {
if (pm. response. code === 429) pm. expect(pm. response. headers. has('Retry-After')). to. be. true;
});

9) Idempotentlik, retralar, paginasiýa

'Idempotency-Key' -ni beriň we şol bir 'id/status' -y berýändigine göz ýetiriň.
'limit/offset '/' cursor', dublikatlaryň we geçişleriň jikme-jikligini synagdan geçiriň.
Synag skriptindäki retraýlary simulýasiýa etmek: şol bir açar bilen yzygiderli jaňlar.

js pm. test ("Idempotent repetition," () => {
pm. sendRequest(pm. request, (err, res2) => {
pm. expect(res2. code). to. eql(pm. response. code);
pm. expect(res2. json(). id). to. eql(pm. response. json(). id);
});
});

10) Newman в CI/CD

10. 1 Başlamak

newman run collection. json \
-e stage-eu. json \
-d data. csv \
--timeout-request 30000 \
--reporters cli,htmlextra,junit \
--reporter-htmlextra-export./reports/report. html \
--reporter-junit-export./reports/junit. xml

10. 2 GitHub Actions (bölek)

yaml
- uses: actions/setup-node@v4 with: { node-version: '20' }
- run: npm i -g newman newman-reporter-htmlextra
- run: newman run collection. json -e stage-eu. json --reporters cli,junit --reporter-junit-export reports/junit. xml
- uses: actions/upload-artifact@v4 with: { name: newman-reports, path: reports }

10. 3 Jenkins/GitLab CI

Milli wizualizasiýa üçin JUnit ('--reporter-junit-export') eksport ediň.
Paýplaynda joblary bölüň: smoke (çalt), regression (doly), security (negatiw/serhet).

10. 4 Docker

docker run --rm -v $PWD:/etc/newman postman/newman \
run collection. json -e stage-eu. json

11) Moki we gözegçilik

Mock servers Postman - front we şertnamalar üçin çalt bloklar.
Monitors - bulutdan (latency, 5xx, SSL) smokalaryň wagtal-wagtal geçmegi.
Repozitoriýada kesgitlenen moklar üçin jogap mysallarynyň faýllaryny saklaň.

12) Synag maglumatlary we arassalamak

Mazmuny dörediň/aýyryň (_bootstrap/_teardown).
Synag obýektlerini 'e2e _' we TTL prefiksi bilen belläň.

js pm. collectionVariables. set("uniq", Date. now()+"_"+Math. floor(Math. random()1e6));

13) Öndürijilik "dyzynda"

• 'pm ölçäň. response. responseTime`;
• 5-10 iterasiýany sürüň we p95/bosagany düzüň;
• agyr çykyş-geçişler - JMeter/k6/Gatling (bu makalanyň daşynda).

14) Lokalizasiýa we köp kärende

Üýtgeýjiler 'tenant', 'region', 'lang'; gurşawda çalşyň.
Synaglar maglumatlaryň tenantlaryň arasynda "akmaýandygyny" barlamaly (BOLA-read, cross-tenant gadaganlyklar).
Sebit aýratynlyklary üçin aýry-aýry kolleksiýalar/bukjalar (çäkler, walýutalar).

15) Hasabat we artefaktlar

CI: HTML habarlaryny saklaň, 'junit. xml ', şowsuz jogaplar (response bodies).
"Slack/Teams" yz habarnamalaryny birikdiriň.

16) Hili we ýapylmagy

• CRUD per-resurs (200/201/204 + negatiwler).
• Awtorizasiýa: rollar/satyn almalar/multi-tenant.
• Paginasiýa/süzgüçler/sortlamak.
• Idempotentlik we retra.
• Çäkler: 413/414/431/429.
• Formatlar we shemalar (JSON Schema/OpenAPI).
• Integrasiýa (HMAC/mTLS bilen webhuklar) - anti-replay.

17) Antipatternler

Negatiw synaglarsyz bir "bagtly ýol".
Kolleksiýada/repozitoriýada uzak ömürli tokenler.
Synag maglumatlaryny nusga maglumatlary bilen garyşdyrmak.
Aç-açan korelýasiýa bolmazdan synaglaryň tertibine gizlin garaşlylyk.
Ullakan data files.
JUnit/HTML hasabatlarynyň ýoklugy → CI-de görünmeýär.

18) Prod-taýynlyk çek-sanawy

• Kolleksiýalar '_ bootstrap/_ teardown' bar.
• dev/stage/prod üçin gurşaw; CI-gizlin ammardan syrlar.
• Pre-request для auth (OAuth2/HMAC); bellikler kesilýär we aýlanýar.
• Synaglar: oňyn + negatiw, shemalar (JSON Shema), paginasiýa, 429/Retry-After.
• Idempotentlik: 'Idempotency-Key' barlagy, goşa çagyryşa deňdir.
• Data-driven CSV/JSON, üýtgeşiklik üçin tötänleýin goşulmalar.
• CI-de Newman: JUnit/HTML hasabatlary, artefaktlar build outputs.
• Esasy ugurlar üçin moki/monitorlar; SLA.
• Üýtgeýjiler, bellikler we işe başlamak tertibi boýunça resminamalar.

19) TL; DR

Synaglaryň logikasyny Postman kolleksiýalarynda saklaň, parametrleri gurşawda saklaň we JUnit/HTML hasabatlary bilen Newman arkaly CI-de geçiň. Negatiwleri, shemalary, idempotentligi, paginasiýany we çäkleri ýapyň. Ädimleriňizi üýtgeýän ädimler bilen baglanyşdyryň, data-driven girelgelerini we mok/monitorlary ulanyň. Syrlar - diňe CI-den, hasabatlar - bild artefaktlary.