Wykładzina API i analiza statyczna

1) Dlaczego link API

• Zapobieganie niekompatybilnym i dorozumianym zmianom
• ujednolicenie statusów, błędów, paginacji, bezpieczeństwa;
• umożliwia weryfikowanie specyfikacji maszyn oraz przewidywanie uwolnień;
• zmniejszyć koszty przeglądu i pobytu na pokładzie.

Zasada: "umowy są sprawdzane automatycznie; PR bez zielonego wiązania nie trzyma"

2) Urządzenia łączące

1. Kontrakty: OpenAPI/AsyncAPI/GraphQL SDL, Protobuf/Avro/JSON Schema.
2. Implementacja: długopisy REST/gRPC, oprogramowanie pośrednie, kody stanu/nagłówki.
3. Infrastruktura: nagłówki bezpieczeństwa, limity, polityka pamięci podręcznej.
4. Powiązane artefakty: przykłady, kolekcje listonoszy, schematy błędów.

3) Podstawowe zasady dla HTTP API (zalecany profil)

3. 1 Notacja i adres URL

snake_case w ciałach JSON, kebab-case w ścieżkach lub uniform kebab-case/'/v1/... '.
Zasoby - liczba mnoga: '/v1/payments ', gniazdowane - '/v1/wallets/{ id }/transactions'.
Identyfikatory jako path-params: '/v1/payments/{ payment _ id} '(typ: string, format: uuid).

3. 2 Metody i statusy

"GET" - 200/206; " POST '- 201 (+ „Lokalizacja”), konflikty - 409; walidacja - 422; limity - 429 (+ „Retry-After”).
Nie zwracaj 200 za błędy. Zapytania warunkowe - 304 przez 'If-None-Match'.

3. 3 Błędy (jednolity format)

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

Wymagane: "kod", "komunikat", "trace _ id'; locale - poprzez „Content-Language”.

3. 4 Paginacja/filtry

Na podstawie kursora: 'page _ size', 'page _ token', отвей: 'next _ page _ token'.
Filtry i sortowanie - whitelisty udokumentowane w 'parametrach'.

3. 5 Bezpieczeństwo

Jednolity system bezpieczeństwa: zakresy OAuth2/OIDC lub mTLS; odmówić 'http' (tylko 'https').
Nie zwracaj czułych nagłówków, żetony maski w przykładach.

3. 6 Ograniczenia i wymiary

Granice tytułu/organu: 413/414/431; Dokumentuj maksymalne dozwolone wartości.

4) Narzędzia i ekosystem

4. 1 OpenAPI

Spectral (JSON/YAML lint), Redocly linter, oas-diff/openapi-diff (semantic diff), schemathesis/dredd (kontrole w toku).

4. 2 Protobuf/gRPC

buf (lint + breaking check), protolint, generatory SDK; gnostyk do analizy.

4. 3 GraphQL

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

4. 4 Linters kod i SAST

ESLint, golangci-lint, Detekt/Ktlint, Pylint/Flake8, Semgrep (zapach API i szablony zabezpieczeń).

5) Przykłady reguł: Spectral/Redocly

5. 1 Widmo (przykład 'widmo. 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 (fragment ".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: profil 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: []

• Nie należy ponownie używać numerów pól; skreślony - w „zarezerwowanym”.
• Nowe pola - „opcjonalne” lub domyślne; nie zmieniać typów/semantyki.

7) Różnica semantyczna i „łamanie” zmian

7. 1 HTTP

• Zmiana typu pola/obowiązkowa
• Usuń stan/trasę/parametr
• zwężenie enum/zakresu;
• zmiana formatu id (uuid → string).

• Dodaj pola opcjonalne
• Nowe statusy, które nie wpływają na szczęśliwą ścieżkę (na przykład udokumentowane '422')
• przedłużenie enum.

7. 2 gRPC/Protobuf

Usuwanie pola bez „zastrzeżonych ”/numeracji - łamanie.
Zmiana typu (int32 → ciąg) - łamanie.
Dodanie nowego znacznika jako opcjonalnego jest zwykle bezpieczne.

8) Łącząc kontrakt i kod

1. Kontrakt → kod: generowanie SDK/serwera stubs, negatywne przykłady w testach.

2. Umowa → kod: testy specyfikacji, automatyczna kontrola statusów/nagłówków.

• disallowing 'return 200' when 'error! = nil';
• obowiązkowe „Idempotence-Key” na trasach płatności pisemnych;
• maskowanie żetonów w dziennikach.

9) rurociąg CI/CD (odniesienie)

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

• nie jest łamanie różnica;
• Naruszono podstawowe zasady (statusy/bezpieczeństwo/błędy)
• nie ma przykładów/opisów parametrów.

10) Katalog zasad (szablon dla organizacji)

Identyfikatory i typy

'_ id' -' ciąg ',' format: uuid '.
Pola pieniężne - „ciąg ”/„ dziesiętny” ze skalą; waluta - ISO-4217.

Błędy

Ujednolicony system (zob. § 3. 3), kody: „400/401/403/404/409/422/429/5xx”.
Zawsze 'trace _ id';' Retry-After 'for 429/503.

Paginacja

Tylko kursor; max 'page _ size' jest udokumentowany.

Bezpieczeństwo

Wszystkie operacje - blok „bezpieczeństwa”; „zakresy” są opisane.
Nie „http:” linki; TLS 1. 2+.

Pamięć podręczna/idempotencja

Мла GET - 'ETag/Last-Modified'; do zapisu - „Idempotence-Key” (w stosownych przypadkach).

Dokumentacja

„summary”, „opis”, przykłady żądań/odpowiedzi (ważne).

11) Przykłady automatycznych kontroli

11. 1 Weryfikacja obowiązkowych nagłówków zabezpieczeń (Spectral)

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

11. 2 openapi-diff (etap pseudo CI)

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

11. 3 buf breaking-check

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

12) Obserwowalność jakości umów

Metryki: udział PRs z błędami łączącymi, czas naprawy, liczba prób łamania, „długi” zgodnie z zasadami.
Deski rozdzielcze: postęp migracji do ujednoliconego systemu błędów, zakres z przykładami, stabilność wersji.

13) Antypattery

"Doc' żyje oddzielnie od kodu → desynchronizacja. Trzymaj umowę blisko usługi i wypuść zmieniony artefakt.
Linter tylko ręcznie. Potrzebuję ciężkiej bramki PR.
Losowe przykłady (nie-deterministyczne) - płatki w kontrolach.
Brak negatywnych przykładów i kodów błędów.
Ponowne wprowadzenie systemu błędów dla każdej usługi.
Ignorowanie kontroli łamania Protobuf (zmiana znaczników „przez oko”).

14) Szczegóły dotyczące iGaming/Finance

Pola walutowe - skala stała/zaokrąglanie; zakaz pływania.
Obowiązkowe nagłówki „X-najemca”, „X-Region” i ślad „traceparent”.
Klamki płatnicze: sprawdzenie dla 'Idempotence-Key', 'Retry-After' i poprawne 409/201 semantyki.
Webhooks PSP/KYC: HMAC/mTLS są opisane w słowach ", anty-powtórka („X-Timestamp”, okno).
Regionalne ograniczenia i lokalizacja błędów („Content-Language”).

15) Lista kontrolna gotowości Prod

• Profile widmowe/Redocly są zaprojektowane i podłączone w bramce pre-commit i PR.
• Jednolity wzór błędu i statusy - zaangażowane i sprawdzone.
• openapi-diff/GraphQL Inspector/buf - zmiany łamania bloku.
• Przykłady żądań/odpowiedzi są ważne; paginacja/filtry udokumentowane.
• Programy i zakresy są wypełnione; Nie ma linków http.
• Dla Protobuf: „zarezerwowany” na skreślonych znacznikach; nowe pola - opcjonalne.
• Semgrep/lintery kodowe włączone; maskowanie sekretów w dziennikach.
• CI publikuje artefakty kontraktowe i raporty linkingowe.
• Playbook: jak działać podczas łamania-diffa (rollback, hotfix, powiadomienia do integratorów).

16) TL; DR

Wdrożenie automatycznego linkowania umów (Spectral/Redocly, buf/GraphQL Inspector) i semantic diff, naprawić jeden błąd/status/pagination/system bezpieczeństwa, podłączyć PR-gate i opublikować kontrakty jako artefakty. Każda rozbijająca się różnica jest światłem hamulcowym. W przypadku pieniędzy/płatności - specjalne zasady (idempotencja, „Retry-After”, HMAC/mTLS).