SDK dizayn və dil dəstəyi

1) SDK məqsədləri və uğur meyarları

Developer Experience (DX): intuitiv API, dillər arasında vahid semantika.
Etibarlılıq: taymaut/retrai/idempotent «qutudan».
Təhlükəsizlik: sirlər, imzalar, TLS, proksi/企业 mühitlə uyğunluq.
Müşahidə: log, metrika, dil üçün standart alətlərdə trass.
İqtisadiyyat: minimum egress/CPU, effektiv paginasiya, batchi.
Sabitlik: ciddi semver, əks uyğunluq, LTS filialları.

2) Memarlıq prinsipləri

1. Thin client, strong contracts: SDK gizli iş məntiqi olmadan protokol (REST/gRPC) üzərində sarğı.
2. Unified surface: eyni anlayışlar (Client, Request, Response, Error, Paginator, WebhookVerifier).
3. Safe by default: ağlabatan vaxtlar, eksponensial backoff + jitter, təkrarlardan qorunma.
4. Config layering: ENV → -fayl → konstruktor → metod parametrləri.
5. Pluggable nəqliyyat: HTTP/gRPC dəyişdirilə bilər, proxy/ bağlantıları ilə uyğun.
6. Testability: interfeys/saxta, dependency injection, record-replay.
7. Səhv I18n: maşın 'error _ code' sabitdir; mesajlar lokallaşdırıla bilər.
8. Accessibility: uyğun olduğu yerdə AsyncClient variantları (adətən 'AsyncClient').
9. Security-first: Sirlər lazım olduqda loglara, PII redaksiyasına, FIPS uyğun kriptoblioteklərə düşmür.

3) Dəstək cədvəli və imkanlar pariteti

4) API baza səthi (kanonik model)

Ümumi mahiyyətlər

Client: nəqliyyat, açar, retras, telemetry hooks.
Request/Response: tipik təhlükəsiz modellər/DTO, paqinasiya/kursorlar.
Error: 'status', 'error _ code', 'trace _ id', 'retriable' ilə vahid sinif.
Paginator/Iterator: vərəqlərin/kursorların tənbəl aşırılması.
WebhookVerifier: HMAC/mTLS yoxlaması, 'event _ id' dedupu.

Mini nümunə (TypeScript)

ts const client = new GambleHubClient({
apiKey: process. env. GH_API_KEY!,
timeoutMs: 10_000,
retries: { max: 5, strategy: "expo-jitter" }
});

const { items, nextCursor } = await client. reports. list({ from, to, cursor });
for await (const report of client. reports. iter({ from, to })) { /... / }

Mini nümunə (Python, async)

py from gamblehub import AsyncClient, WebhookVerifier

client = AsyncClient(api_key=API_KEY, timeout=10, retries={"max":5})
async for user in client. users. iter(updated_after=ts):
...

verifier = WebhookVerifier(secret=WEBHOOK_SECRET)
if verifier. verify(headers, body): ack()

5) Konfiqurasiya və icra mühiti

ENV: `GH_API_KEY`, `GH_ENDPOINT`, `GH_TIMEOUT_MS`, `HTTP_PROXY/HTTPS_PROXY`, `GH_REGION`.
Konstruktor: ENV-ni yenidən təyin edir.
Per-call overrides: metod səviyyəsində zaman/retraj.
TLS/mTLS: sertifikat/açar yolu, lazım olduqda CA pin.
Bağlantı hovuzları: keep-alive, HTTP/2, paralelliyin məhdudlaşdırılması.

6) Qutudan təhlükəsizlik

Sirləri: loqo deyil, stack traces gizlətmək; redaction ``.
İmzalar: HMAC vebhuk, 'X-Key-Id '/açar rotasiyası, «iki açar» aktiv/next dəstəyi.
İdempotentlik: write əməliyyatları üçün şəffaf 'Idempotency-Key' quraşdırılması (yenidən başlamaq təhlükəsizdir).
RBAC/Scopes: alıcılar üçün rahat siyahılar/sabitlər.
PII siyasəti: Loging zaman standart redaktə interfeysləri.

7) Etibarlılıq: Taymaut, retrai, back off

Default vaxt: 10-15s; 3-5s konnekt.
Retrailer: 5xx/408/429 üçün ('Retry-After' hörmət), eksponent backoff + jitter, cəhd/vaxt həddi.
Circuit-breaker: isteğe bağlı SDK (və ya üçüncü tərəf libaları üzrə tövsiyələr).
İdempotent write: açar avtomatik təkrar; toqquşmalar → qaldırmaq '409 IDEMP_REPLAY'.

8) Paginasiya, kursorlar və axın

Kursor/iterator: transient səhvlər zamanı tənbəl aşırma, avtomatik təkrarlama.
Keyset-pagination: sabit nizamlama '(updated_at,id)'.
Backpressure: eyni vaxtda sorğu limiti; в async-SDK — `async for`/`channels`.
Streaming (harada mövcuddur): SSE/WebSocket/gRPC-stream avto-reconnect və 'sequence' dedupu ilə.

9) Səhvlər və müqavilə

• `ApiError` (базовый) → подтипы: `AuthError(401)`, `PermissionError(403)`, `NotFound(404)`, `Conflict(409)`, `RateLimit(429)`, `ValidationError(422)`, `ServerError(5xx)`.
• Свойства: `status`, `error_code`, `message`, `trace_id`, `retriable`, `details`.
• Best practice: mesajlar - insan oxunan, 'error _ code' - sabitdir.

10) Dil deyimləri

TypeScript/JS

Promise-based + paqinasiya üçün generatorlar; ESM + CJS paketləri.
Tree-shaking, minimal polifillər, abort siqnalları ('AbortController').

Python

Sync + Async (aiohttp/httpx), kontekst menecerləri, 'pydantic' modelləri (və ya dataclasses).
Wheels для linux/macos/windows; proxies/NO_PROXY dəstəyi.

Java

'CompletableFuture' (lazım olduqda), 'AutoCloseable', 'Duration', 'Executor'.
HTTP client: `java. net. http 'və ya OkHttp; SLF4J qeydlər üçün.

Go

Kontekstlər 'context. Context`, `http. Client 's tuned Transport, testlər üçün interfeyslər.
Error wrapping (`fmt. Errorf («% w», err) '), sentinel səhvlərinin semantikası.

.NET

`HttpClientFactory`, `CancellationToken`, `IAsyncEnumerable<T>`.
Polly siyasətləri (retry/circuit-breaker).

... PHP/Ruby üçün (PSR-18, Faraday/Net:: HTTP).

11) Loging, metrika, izləmə

Log: (ERROR/WARN/INFO/DEBUG) səviyyələri, 'trace _ id' korelyasiyası, həssas məlumatların kəsilməsi.
Метрики: `requests_total`, `errors_total{status}`, `retry_count`, `latency_ms`, `throttled_total`.
Yollar: OpenTelemetry hooks (API çağırışına span, endpoint, status, retry atributları).
Debug-mode: 'GH _ SDK _ DEBUG = 1' mühit dəyişəni - HTTP başlıqlarının (sirrsiz) və zamanların çapı.

12) Sənədləşmə və nümunələr

Quickstart 5 dəqiqə: auth, ilk sorğu, pagination, emal 429.
Cookbook: webhook (imza yoxlama), idempotent write, replay.
API kataloqu: OpenAPI/Protobuf-dan avtogen, lakin «əl» nümunələri ilə.
Snippets: məşhur tapşırıqlar üçün hazır kod parçaları (Python/TS/Java/Go/.NET).

13) Generation vs əl kodlaşdırma

Kombinə yanaşma: codegen (modellər/müştərilər) + ergonomics/idempotentlik/paginators üçün əl «qələmləri».
Şablonlar: metodların vahid adları ('create/get/list/update/delete'), stab. siqnatura.
Regen (CI-gate) sonra «diff-uyğunluq» yoxlanılması.

14) Version, uyğunluq və deprekasiya

SemVer: X.Y.Z. sındırıcı - yalnız major.
Sabitlik siyasəti: minor relizlər - sahələr/metodlar əlavə edin, müqavilələri dəyişdirməyin.
Deprecation: şərhlər/ @Deprecated/Obsolete atributları, proses üçün bir dəfə icarə xəbərdarlıqları, pəncərə ≥ 90 gün.
LTS filialları: kritfiks backport (yeni sahə olmadan).

15) Releases və təchizat zənciri

CI/CD: linterlər/formatterlər, unit + integration, müqavilə testləri, qum qutusuna qarşı e2e.
Artefaktların imzası: Sigstore/GPG, buraxılışlarda checksums.
Nəşr: npm/PyPI/Maven/NuGet/Go/Composer/RubyGems ilə changelog və release notes.
SemVer gate: ictimai API-nin avto uyğunluq testi (məsələn, 'apiregistry diff').

16) Test (keyfiyyət matrisi)

Unit: modellər, serializasiya, validasiya, retrailer/taymautlar.
Contract: OpenAPI/Protobuf sxemlərinə qarşı (negative/edge cases).
Integration: vs sandbox (idempotentlik, 429/5xx, webhooks).
Load/soak: pagination/stream, backpressure.
Fuzz: sahələr/başlıqlar/zaman sərhədləri.
Compat: köhnə SDK, yeni API və əksinə.
Smoke-pack: CI reqress tutmaq üçün 5 dəqiqə.

17) Telemetriya və məxfilik siyasəti

Opt-in: PII olmadan yığılmış SDK metrlərinin (versiya, dil, statuslar) toplanması.
: 'telemetry: off' anonymized 'full' (default off/anonymized).
Şəffaflıq: nəyi və nə üçün toplandığını sənədləşdirin; Söndürmə seçimini verin.

18) Performans və FinOps

Batching: kiçik sorğuları birləşdirmək; RPS məhdudlaşdırmaq; gzip/br.
ETag/If-None-Match caching, şərti GET.
İqtisadi modellər: yaddaşa hər şeyi yükləmək əvəzinə tənbəl iteratorlar.
Limitlə paralellik: 'max _ concurrency' API-nin «DDOS» olmaması üçün.

19) SDK standart komponentləri (skeletlər)

Error (TypeScript)

ts export class ApiError extends Error {
constructor(
readonly status: number,
readonly errorCode: string,
readonly traceId?: string,
readonly retriable?: boolean,
readonly details?: unknown
) { super(`${status} ${errorCode}`); }
}

Paginator (Python)

py class Paginator(Generic[T]):
def __init__(self, fetch_page):
self._fetch = fetch_page self._cursor = None async def __aiter__(self):
while True:
page = await self._fetch(self._cursor)
for item in page. items:
yield item if not page. has_more: break self._cursor = page. next_cursor

WebhookVerifier (Go)

go func Verify(body []byte, signatureHeader, secret string) bool {
parts:= strings. SplitN(signatureHeader, "=", 2)
mac:= hmac. New(sha256. New, []byte(secret))
mac. Write(body)
expected:= base64. StdEncoding. EncodeToString(mac. Sum(nil))
return hmac. Equal([]byte(parts[1]), []byte(expected))
}

20) Dəstək, SLA və icma

SDK ilə SLA: kritik baqlar - fix ETA, rabitə kanalları, uyğunluq matrisi (SDK API).
Issue templates: bug/feature/question, auto-triage/versiyası.
Roadmap/labels: «good first issue», «help wanted».
Security policy: `SECURITY. md ', zərurət hesabatları üçün kanal, lazım olduqda CVE.

21) SDK keyfiyyət çek siyahısı

• Vahid səhv modeli ('status', 'error _ code', 'trace _ id', 'retriable').
• Vaxt/retrailer/jitter, hörmət 'Retry-After'.
• Idempotency write, avtomatik 'Idempotency-Key'.
• Pagination kursor, tənbəl iteratorlar/axınlar.
• HMAC/mTLS və dedup ilə WebhookVerifier.
• ENV/konstruktor/parametrləri vasitəsilə konfiqurasiya.
• Log/Metrics/OTel-huki, gizli debug rejimi.
• SemVer, deprekasiya ≥ 90 gün, LTS filialları.
• Məşhur vəzifələr üçün tam nümunələr və Cookbook.
• CI dillər arasında fich paritet matrisi.

22) Tətbiq planı (3 iterasiya)

1. MVP (2-3 həftə): əsas Client, auth, 3-5 əsas end-point, paginasiya, vahid səhv-model, retrailer/vaxt; TS+Python.
2. Scale (3-5 həftə): Java/Go/.NET, WebhookVerifier, idempotentlik write, telemetriya hooks, OpenAPI modellərinin yaradılması.
3. Pro (davamlı): axın/SSE/gRPC, perf-optimizasiya, LTS filialları, qabaqcıl Cookbook, miqrasiya/deprekasiya vasitələri.

23) Mini-FAQ

Hər şeyi yaratmaq və ya əllərinizlə yazmaq?
Modellər/müştərilər və ergonomics (paginatorlar, retralar, idempotentlik, rahat işarələr) - əl ilə yaradın.

Ayrı async-SDK lazımdır?
В Python — да (`AsyncClient`); JS - default; v.NET/Java - mümkün qədər asenxron çağırışlar.

Dillərin paritetini necə saxlamaq olar?
CI fich matrisi, «kəmərlər üzrə» buraxılışlar (TS → Py → Java → Go → .NET) avto-reportla «nə geridə qalır».

Yekun

Güclü SDK bütün dillərdə eyni olan vahid səth, etibarlı defolt və proqnozlaşdırıla bilən müqavilələrdir. Tərtibatçılara təhlükəsiz «qutudan» konfiqurasiya, başa düşülən səhv modeli, rahat paqinasiya və vebhuk yoxlaması verin, keyfiyyətli sənədləşmə və ciddi semver ilə tamamlayın. Sonra inteqrasiyalar sürətli, dəstək ucuz, ekosistem isə davamlı və miqyaslı olacaq.