API şertnama synagy

1) Näme üçin şertnama synagy

Şertnama müşderiniň garaşyşlaryny we üpjün edijiniň wadalaryny: ugurlaryny/usullaryny, sözbaşylaryny, jisimleriň shemalaryny, statuslaryny, ýalňyşlyklaryň semantikasyny we çäklendirmelerini kesgitleýär. Maksat goşulmazdan ozal gabat gelmeýän üýtgeşmeleri tutmak we wersiýalary howpsuz, agyr E2E goýbermekdir.

2) Çemeleşmeler

Consumer-Driven Contracts (CDC): müşderi garaşýanlary emele getirýär (Pact we analoglar); üpjün ediji olary yzygiderli barlaýar.
Aýratynlyk: ýeke-täk hakykat çeşmesi hökmünde şertnama (OpenAPI/Protobuf/GraphQL SDL); synaglar spesifikasiýa garşy durmuşa geçirilmegini tassyklaýar.
Waka: habarlaryň shemalary (Euro/JSON Schema/Protobuf) + dellalda/sanawda laýyklyk düzgünleri.

3) HTTP/REST: spesifikasiýa akymy

1. Şertnama: OpenAPI 3. x (shemalar, mysallar, kodlar).
2. Lint we statanaliz: stil, hökmany meýdanlar, bitewi kodlar.
3. Durmuşa geçirişiň tassyklamasy: OpenAPI-e garşy synag generatory (schemathesis/Dredd-çemeleşme) + el negatiwleri.
4. Snapshotlar: jogaplaryň mysallaryny, ETag semantikasyny, idempotentligiň sözbaşylaryny ýazga alyň.

yaml paths:
/v1/payments:
post:
responses:
"201": { $ref: "#/components/responses/PaymentCreated" }
"409": { description: Duplicate by Idempotency-Key }
"422": { description: Schema/Business validation failed }

4) CDC (Pact çemeleşmesi)

1. "Consumer" synagy ýazýar, pact-faýly emele getirýär.

2. Dellalda çap etmek (artefakt).

3. CI-de Provider hyzmaty (ýa-da şertnama-sütünini) ýokarlandyrýar, pactlary barlaýar.

4. Dellal can-i-deploy laýyklyk matrisini hasaplaýar.

js pact
.given("wallet exists")
.uponReceiving("get wallet")
.withRequest({ method:"GET", path:"/v1/wallets/w123", headers:{ "Authorization": term({generate:"Bearer x", matcher:/^Bearer\s.+/}) }})
.willRespondWith({
status: 200,
headers: { "Content-Type": "application/json" },
body: like({ id:"w123", currency: "EUR", balance: 0 })
});

5) gRPC/Protobuf şertnamalary

Bukjalaryň/hyzmatlaryň wersiýasy bilen şertnama - '.proto'.
Gabat gelmek: bellikleri gaýtadan ulanmaň, diňe optional bilen täzelerini goşuň, ulanylýan ýerleri aýyrmaň; belgileri saklamak.
Synaglar: serwer/müşderi stabiniň emele gelmegi, awtomatiki döredilen ýagdaýlaryň kärendesi + negatiwler (unknown fields, size-limits).

6) Waka şertnamalary (Kafka/NATS/...)

Схемы: Avro/JSON Schema/Protobuf в Schema Registry.
Laýyklyk syýasaty: 'BACKWARD' (köplenç ýeterlik) ýa-da 'FULL'.
Prodýuser synaglary: shema garşy habary tassyklaýar; konsumer synaglary: köne we täze wersiýany kabul edýär.
Inwariantlar: idempotentligiň açarlary, tertibi/gaýtalanmagy, duplikasiýa semantikasy.

json
{"type":"record","name":"PayoutCreated","fields":[
{"name":"payoutId","type":"string"},
{"name":"amount","type":"double"},
{"name":"currency","type":{"type":"string","logicalType":"iso-4217"}}
]}

7) Gabat gelmek we wersiýalary

Backward-compatible (maslahat berilýän minimal): Bar bolan ýerleriňizi bozmaň.
Forward-compatible: Sarp edijiler näbelli ýerleri äsgermezlik edýärler.
Doly: ikisi hem.
Wersiýasy: 'path (/v1)', 'Accept: application/vnd. brand. v2+json`, `proto package v2`.
Deprecation-syýasat: çykyş penjiresi (mysal üçin 90 gün), duýduryş sözbaşylary/wakalar.

8) Negatiw we ýalňyşlyklar hem şertnama

Kodlary standartlaşdyryň: 400/401/403/404/409/422/429/5xx, hökmany meýdanlar 'code', 'message', 'trace _ id'.
Ölçegler/çäkler - şertnamanyň bir bölegi (413/414/431).
Idempotentlik: gaýtalananda özüni alyp barşy (409 vs 201 same id).
Başlyklar: 429/503-de 'Retry-After', 'Idempotency-Key', 'Content-Language' we ş.m.

json
{ "code":"validation_error", "message":"amount must be ≥ 1", "trace_id":"..." }

9) Maglumatlary şertnama dolandyrýar

Mysallar/geýim jogaplary (examples) - janly, CI-de tassyklanýar.
CDC üçin fiksturlar - minimal, kesgitlenen.
Maglumatlary döretmek - sanlar/seneler üçin property-based; ýöne snapshotlaryň durnuklylygyny bozmaň.

10) CI/CD-de Pipline (salgylanma)

1. Lint/validate: OpenAPI/Proto/Avro (`validate`, style-линер).
2. Publish: kontrakt artefakt hökmünde (dellal/reýestr).
3. Verify: üpjün ediji CDC paketlerini/spesifikasiýa synaglaryny geçirýär.
4. can-i-deploy gate: ýaşyl matrisa bolmasa goýbermek gadagandyr.
5. Diff: üýtgeşmeleriň gabat gelýändigini barlamak (semantic diff).
6. Hasabat: JUnit/HTML, düzgün bozmalar/kemçilikler sanawy.

yaml jobs:
lint:...
publish-contract: needs: [lint]
verify-provider: needs: [publish-contract]
can-i-deploy:
if: always()
steps: [run: pact-broker can-i-deploy...]

11) Gurallar (wezipeleriň synplary boýunça)

Lint/walidatorlar: openapi-linters, protobuf-lint, euro-tools.
CDC: Pact-maşgala/broker, Spring Cloud Contract, Hoverfly (HTTP ýazgylary/repliterleri).
Aýratynlyklary: schemathesis/Dredd-şuňa meňzeş çemeleşme, Postman test + JSON Shema.
Diff: semantic-diff OpenAPI/Proto/Euro (breaking-üýtgeşmeleri ýüze çykarýar).
Konteýnerler: Üpjün edijini/şertnamalaryň sütünini götermek üçin Testcontainers.

12) Antipatternler

"Spetsdok" koddan aýratyn → rasinhronizasiýa. Şertnamany hyzmatyň ýanynda saklaň.
Şertnamanyň ýerine daşarky hyzmatyň moki → täzelenmelerde gowşaklyk.
Tötänleýin jogaplar/→ fleýka shemasyna baglanyşyksyz nesil.
Görnüşsiz meýdanlaryň görnüşini/borçlylygyny üýtgetmek.
Habarnamasyz/deprekasiýasyz silent-giňeldişler.
Negatiw şertnamalaryň we ýalňyşlyk kodlarynyň ýoklugy.

13) iGaming/Maliýe aýratynlyklary

Pul meýdançalaryny resmileşdiriň: 'amount' - masştably decimal, walýuta - ISO-4217, mukdaryň üýtgemegi.
Töleg/webhuk şertnamalary: HMAC/mTLS, anti-replay ('X-Timestamp' penjiresi), idempotentlik, 'Retry-After'.
Sebitlilik/tenantlar: hökmany sözbaşylar 'X-Tenant/X-Region', habarlaryň lokalizasiýasy.
Wakalar: üýtgemeýän magazinesurnallar (audit), deduplikasiýa açarlary, eltip bermek kepillikleri (at least once + idempotent hendlerler).

14) Synaglaryň "skeletleriniň" mysallary

14. 1 Schemathesis-stil (psevdo)

bash schemathesis run openapi. yaml --checks all --hypothesis-deadline=200

14. 2 Postman spesifikasiýa ranner hökmünde

js pm. test ("Scheme/v1/wallets/{ id} is valid," () => {
const schema = pm. collectionVariables. get("wallet_get_schema");
pm. expect(ajv. validate(JSON. parse(schema), pm. response. json())). to. be. true;
});

14. 3 CDC-iň provider barlagy (psevdo)

bash pact-broker can-i-deploy --pacticipant wallets --version $SHA --to-environment staging

15) Prod-taýynlyk çek-sanawy

• Repozitoriýadaky şertnamalar, CI eserleri tassyklaýar we neşir edýär.
• CDC möhüm integrasiýa üçin goşuldy; broker/matrix "can-i-deploy" işleýär.
• Laýyklyk syýasaty (HTTP/gRPC/Events) resminamalaşdyryldy; awtomatiki semantic-diff.
• Negatiw şertnamalar: ýalňyşlyklar, ululyk çäkleri, idempotentlik, 'Retry-After'.
• Synag maglumatlary kesgitlendi; mysallaryň snapshotlary goldanylýar.
• Wersiýalaşdyrmak we deprecation: möhletler, habarnamalar, sözbaşylar.
• Wakalar üçin - Shema registry we laýyklyk tertibi; prodýuser/konsumer iki wersiýany hem synagdan geçirýär.
• Artefaktlar: JUnit/HTML, diff/verify hasabatlary, laýyklyk matrisi.
• Waka-prosedura: şertnamanyň çalt rollback/ficha-baýdak, integratorlara habar bermek.

16) TL; DR

Şertnamalarda garaşylýanlary ýazga alyň we awtomatiki usulda kowuň: Müşderiniň garaşyşlary üçin CDC, durmuşa geçirişe laýyk gelmek üçin spesifikasiýa synaglary, wakalar üçin shemalaryň sanawy. Berk laýyklyk syýasatyny we negatiw şertnamalary saklaň (ýalňyşlyklar, çäkler, deňagramlylyk). Greenaşyl can-i-deploy matrisasyz we semantic-diff breaking-üýtgeşmesiz çykarylyp bilinmez.