API ლინტინგი და სტატიკური ანალიზი

1) რატომ უნდა მოიქცეს API

• ხელს უშლის შეუთავსებელ და არაპირდაპირი ცვლილებებს;
• სტატუსების, შეცდომების, პაგინაციის, უსაფრთხოების შერწყმა;
• გახდის სპეციფიკაციებს გადამოწმებული და გამოშვებები პროგნოზირებადი;
• შეამცირეთ შურისძიების ღირებულება და ონბორდის დრო.

პრინციპი: "კონტრაქტები ავტომატურად შემოწმებულია; PR არ დაიშლება მწვანე რგოლის გარეშე."

2) ობიექტები

1. კონტრაქტები: OpenAPI/AsyncAPI/GraphQL SDL, Protobuf/Avro/JSON Schema.
2. განხორციელება: REST/gRPC სახელურები, middleware, სტატუსის კოდი/სათაურები.
3. ინფრასტრუქტურა: უსაფრთხოების სათაურები, ლიმიტები, ქეშის პოლიტიკოსები.
4. დაკავშირებული ნიმუშები: მაგალითები (examples), Postman კოლექციები, შეცდომების ნიმუშები.

3) ძირითადი წესები HTTP API (რეკომენდებული პროფილი)

3. 1 ნოტაცია და URL

snake _ case სხეულებში JSON, kebab case ბილიკებში ან ერთგვაროვანი kebab-case/'/v1/... ".
რესურსები - მრავლობითი: '/v1/payments ', ინვესტიცია - '/v1/wallets/{ id/transactions'.
იდენტიფიკატორები, როგორც path-params: '/v1/payments/{ payment _ id '(ტიპი: string, ფორმატი: uid).

3. 2 მეთოდები და სტატუსები

'GET' - 200/206; 'POST' - 201 (+ 'Location'), კონფლიქტები - 409; ვალიდაცია - 422; ლიმიტები - 429 (+ 'Retry-After').
არ დააბრუნოთ 200 შეცდომისთვის. პირობითი მოთხოვნებია 304 'If-None-Match'.

3. 3 შეცდომა (ერთი ფორმატი)

json
{ "code":"validation_error", "message":"amount must be ≥ 1", "trace_id":"...", "details":[{"field":"amount","reason":"min:1"}] }

სავალდებულოა: 'code', 'მესიჯი', 'trace _ id'; ლოკალი - 'შინაარსის ენის' საშუალებით.

3. 4 პაგინაცია/ფილტრები

Cursor-based: `page_size`, `page_token`, ответ: `next_page_token`.
ფილტრები და დახარისხება - whitelists, დოკუმენტირებული 'parameters'.

3. 5 უსაფრთხოება

ერთჯერადი უსაფრთხოების სქემა: OAuth2/OIDC scopes ან mTLS; აკრძალეთ 'http' (მხოლოდ 'https').
არ დააბრუნოთ მგრძნობიარე სათაურები, შეავსოთ ნიშნები მაგალითებში.

3. 6 შეზღუდვები და ზომები

სათაურების/სხეულის ლიმიტები: 413/414/431; აღწერეთ მაქსიმალური დასაშვები მნიშვნელობები.

4) ხელსაწყოები და ეკოსისტემა

4. 1 OpenAPI

სპექტრული (JSON/YAML ლინტი), Redocly linter, oas-diff/openapi-diff (semantic diff), schemathesis/dredd (შესრულებული შემოწმებები).

4. 2 Protobuf/gRPC

buf (lint + breaking check), protolint, SDK გენერატორები; gnostic ანალიზისთვის.

4. 3 GraphQL

graphql-schema-linter, graphql-inspector (breaking).

4. 4 კოდი ლინტერი და SAST

ESLint, golangci-lint, Detekt/Ktlint, Pylint/Flake8, Semgrep (API სუნი და უსაფრთხოების შაბლონები).

5) წესების მაგალითები: Spectral/Redocly

5. 1 სპექტრული (მაგალითი 'spectral. yaml`)

yaml extends: ["spectral:oas", "spectral:asyncapi"]
rules:
openapi-tags: off info-contact: error no-http: error path-kebab-case:
description: "Paths must be kebab-case"
given: "$.paths[]~"
severity: error then:
function: pattern functionOptions: { match: "^/(?:[a-z0-9]+(?--[a-z0-9]+)/?)+$" }
response-error-schema:
description: "Error responses must use standard schema"
given: "$.paths[][].responses[?(@property >= '400')]"
then:
field: "content.application/json.schema.$ref"
function: truthy id-as-uuid:
given: "$..parameters[?(@.name =~ /.id$/i)]"
then:
field: schema.format function: enumeration functionOptions: { values: ["uuid"] }

5. 2 Redocly (ფრაგმენტი '.redocly. yaml`)

yaml apis:
main: openapi.yaml lint:
extends:
- recommended rules:
no-ambiguous-paths: error operation-2xx-only: off operation-success-response:
severity: error where:
subject: response filterInParentKeys: ["200","201","204"]
operation-security-defined: error no-plain-http: error

6) Protobuf/gRPC: buf პროფილი

6. 1 `buf. yaml`

yaml version: v2 modules:
- path: proto lint:
use:
- DEFAULT except:
- PACKAGE_VERSION_SUFFIX # используем v1 в package breaking:
use:
- WIRE_JSON deps: []

• არ გამოიყენოთ მინდვრის ნომრები; წაშლა - „გამოჯანმრთელებაში“.
• ახალი ველები - 'optional' ან ნაგულისხმევი; არ შეცვალოთ ტიპები/სემანტიკა.

7) სემანტიკური დიფი და „გატეხილი“ ცვლილებები

7. 1 HTTP

• ველის ტიპის/სავალდებულო შეცვლა;
• სტატუსის/მარშრუტის/პარამეტრის მოცილება;
• enum/დიაპაზონის შევიწროება;
• ფორმატის შეცვლა id (uid-string).

• არჩევითი ველების დამატება;
• ახალი სტატუსები, რომლებიც გავლენას არ ახდენს happy-path- ზე (მაგალითად, დოკუმენტირებული '422');
• enum გაფართოება.

7. 2 gRPC/Protobuf

ველის წაშლა 'reserved '/ნომრის შეცვლის გარეშე - breaking.
ტიპის შეცვლა (int32-string) - breaking.
ახალი ჭდის დამატება, როგორც optional, ჩვეულებრივ safe.

8) ხელშეკრულებებისა და კოდების ლინტირების კავშირი

1. კონტრაქტი - კოდი: SDK/სერვერის დანამატის წარმოება, ტესტებში უარყოფითი მაგალითები.

2. KOATUU ხელშეკრულება: სპეციფიკაციის ტესტები, სტატუსის/სათაურების ავტომატური შემოწმება.

• აკრძალვა 'return 200' in 'error! = nil';
• სავალდებულო „Idempotency-Key“ გადახდის მარშრუტებზე;
• ნიშნების შენიღბვა ლოგებში.

9) CI/CD pipline (რეფერენდუმი)

pre-commit: spectral lint, redocly lint
PR gate:  openapi-diff (base..PR), buf breaking-check, graphql-inspector build:   schemathesis smoke, unit/integration linters (ESLint/golangci-lint)
release:  publish contracts (artifact/broker), sign & tag

• არსებობს breaking-diff;
• დაირღვა ძირითადი წესები (სტატუსი/უსაფრთხოება/შეცდომები);
• არ არსებობს პარამეტრების მაგალითები/აღწერილობები.

10) წესების კატალოგი (შაბლონი თქვენი ორგანიზაციისთვის)

იდენტიფიკატორები და ტიპები

`_id` — `string`, `format: uuid`.
ფულადი ველები - 'string '/' decimal' სკალით; ვალუტა - ISO-4217.

შეცდომები

ერთიანი სქემა (იხ. § 3. 3), კოდი: '400/401/403/404/409/422/429/5xx'.
ყოველთვის 'trace _ id'; 'Retry-After' 429/503.

პაგინაცია

მხოლოდ cursor; max 'page _ size' დოკუმენტირებულია.

უსაფრთხოება

ყველა ოპერაცია - "უსაფრთხოების ბლოკი; აღწერილია 'scopes'.
არა 'http:' ბმულები; TLS 1. 2+.

კეში/იდემპოტენტობა

Для GET — `ETag/Last-Modified`; write- ისთვის - 'Idempotency-Key' (სადაც გამოიყენება).

დოკუმენტაცია

'sumary', 'description', მოთხოვნის/პასუხების მაგალითები (ნამდვილი).

11) ავტომატური შემოწმების მაგალითები

11. 1 სავალდებულო უსაფრთხოების სათაურების შემოწმება

yaml security-headers:
given: "$.paths[][].responses['200'].headers"
then:
function: truthy

11. 2 openapi-diff (ფსევდო CI ნაბიჯი)

openapi-diff --fail-on-incompatible base.yaml pr.yaml

11. 3 buf breaking-check

buf breaking --against '.git#branch=main'

12) კონტრაქტების ხარისხის დაკვირვება

მეტრიკა: PR- ის წილი შეცდომების შეცდომებით, ფიქსაციის დრო, ყალბი მცდელობების რაოდენობა, წესების შესაბამისად „დავალიანება“.
დაშბორდები: მიგრაციის პროგრესი შეცდომების ერთიან სქემაზე, მაგალითების დაფარვა, ვერსიების სტაბილურობა.

13) ანტიპატერები

დოქი ცხოვრობს კოდიდან დამოუკიდებლად - რასინქრონიზაცია. შეინარჩუნეთ კონტრაქტი მომსახურების გვერდით და გამოსცეს ვერსირებული არტეფაქტი.
ლინტერი მხოლოდ ხელით. გჭირდებათ მძიმე PR-gate.
შემთხვევითი მაგალითები (non-deterministic) - ფლეიკები შემოწმებებში.
უარყოფითი მაგალითებისა და შეცდომების კოდების არარსებობა.
შეცდომების სქემის ხელახლა შეძენა თითოეული მომსახურებისთვის.
Protobuf- ის შემოწმების უგულებელყოფა (ჩანართების შეცვლა „თვალზე“).

14) iGaming/ფინანსების სპეციფიკა

ფულადი ველები - ფიქსირებული მასშტაბი/დამრგვალება; აკრძალვა

სავალდებულო სათაურები 'X-Tenant', 'X-Region' და 'traceparent'.
გადახდის სახელურები: Idempotency-Key, 'Retry-After' და სწორი 409/201 სემანტიკა.
ვებჰუკები PSP/KYC: HMAC/mTLS აღწერილია 'Schemes' - ში; anti-replay ('X-Timestamp', ფანჯარა).
რეგიონალური შეზღუდვები და შეცდომების ლოკალიზაცია ('შინაარსი-ენა').

15) მზადყოფნის სიის სია

• Spectral/Redocly პროფილები შედგენილია და უკავშირდება pre commit და PR-gate.
• შეცდომების ერთიანი სქემა და სტატუსები - დაფიქსირდა და შემოწმებულია.
• openapi-diff/GraphQL Inspector/buf - ბლოკავს breaking ცვლილებებს.
• მოთხოვნის/პასუხების მაგალითები რეალურია; პაგინაცია/ფილტრები დოკუმენტირებულია.
• Schemes და scopes ივსება; http ბმულები არ არის.
• Protobuf- ისთვის: „აღდგენა“ დისტანციურ ტეგებზე; ახალი ველები - optional.
• Semgrep/linters კოდი ჩართულია; საიდუმლოებების შენიღბვა ლოგებში.
• CI აქვეყნებს კონტრაქტების არტეფაქტებს და ლინტინგის ანგარიშებს.
• Playbuk: როგორ ვიმოქმედოთ rollback-dipe (rollback, hotfix, ინტეგრატორებისთვის შეტყობინებები).

16) TL; DR

დანერგეთ ავტომატური კონტრაქტების ლინზები (Spectral/Redocly, buf/GraphQL Inspector) და სემანტიკური diff, დააფიქსირეთ შეცდომების/სტატუსის/პაგინაციის/უსაფრთხოების ერთჯერადი სქემა, დააკავშირეთ PR-gate და ხელშეკრულებების გამოქვეყნება არტეფაქტებად. ნებისმიერი გადახდა - გაჩერების სიგნალი. ფულისთვის/გადახდისთვის - სპეციალური წესები (idempotence, 'Retry-After', HMAC/mTLS).