> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/tr/admin-api/api-reference.md). # Admin API genel bakış Kangal Admin API; tenant, gateway, routing kaynakları, policy'ler, yapılandırma bundle'ları, gözlemlenebilirlik, SLO ve yönetim credential'larını yönetir. Bu sayfa uygulanmış route'ların ortak kurallarını açıklar; endpoint'e özel request/response modellerinin tamamı için üretilen OpenAPI şemasını kullanın. ## Base URL ve sürümleme Güncel API sürümü `v1`'dir: ```bash export KANGAL_URL='https://kangal.example.com' curl -fsS "$KANGAL_URL/api/versions" | jq curl -fsS "$KANGAL_URL/openapi.json" -o kangal-openapi.json ``` Uygulama hem `/admin/...` hem `/api/v1/admin/...` yollarını kaydeder. Yeni istemciler `/api/v1/admin/...` kullanmalıdır; böylece sonraki sürüme geçiş açıkça yönetilir. FastAPI interaktif dokümantasyonu normalde `/docs` adresindedir; deployment ingress seviyesinde bunu kısıtlayabilir. OpenAPI belgesi endpoint alanları ve durum kodları için temel envanterdir. ## Authentication Her Admin API isteğinde bearer token gönderin: ```bash export KANGAL_TOKEN='kangaladm_...' curl -fsS \ -H "Authorization: Bearer $KANGAL_TOKEN" \ "$KANGAL_URL/api/v1/admin/gateways?tenant_id=tenant-acme" | jq ``` Admin API token'ları `POST /api/v1/admin/api-tokens` ile oluşturulur, `kangaladm_` ile başlar ve plaintext yalnızca oluşturma anında döner. Kullanıcı access/refresh token'ları `POST /auth/login` ile alınır. Rol, scope ve tenant davranışı için [Authentication, pagination ve hatalar](/tr/admin-api/auth-pagination-errors.md) bölümüne bakın. ## Endpoint aileleri | Aile | Örnek path'ler | Notlar | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | Gateway |

/api/v1/admin/gateways
/api/v1/admin/gateways/{gateway\_id}/overview
/api/v1/admin/gateways/{gateway\_id}/traffic/recent

| Tenant gateway yönetimi ve operasyonel genel görünüm. | | Service ve route |

/api/v1/admin/gateways/{gateway\_id}/services
/api/v1/admin/gateways/{gateway\_id}/routes

| Gateway yönlendirme kaynakları. | | Upstream ve target |

/api/v1/admin/gateways/{gateway\_id}/upstreams
/api/v1/admin/gateways/{gateway\_id}/targets
/api/v1/admin/gateways/{gateway\_id}/targets/upstream/{upstream\_id}

| Backend havuzları ve target örnekleri. | | Certificate ve SNI |

/api/v1/admin/gateways/{gateway\_id}/certificates
/api/v1/admin/gateways/{gateway\_id}/ca-certificates
/api/v1/admin/gateways/{gateway\_id}/snis

| Gateway altındaki TLS materyali ve hostname eşleştirmesi. | | Consumer ve credential |

/api/v1/admin/consumers
/api/v1/admin/consumer-credentials
/api/v1/admin/consumer-groups

| İstemci kimliği ve politika gruplama. | | Admin API token | `/api/v1/admin/api-tokens` | Makine kimlik bilgisinin yaşam döngüsü. | | Yapılandırma |

/api/v1/admin/config/export
/api/v1/admin/config/validate
/api/v1/admin/config/diff
/api/v1/admin/config/import
/api/v1/admin/config/sync
/api/v1/admin/config/snapshots
/api/v1/admin/config/snapshots/{snapshot\_id}/rollback

| Bildirimsel yapılandırma ve kurtarma. | | Gözlemlenebilirlik |

/api/v1/admin/observability/summary
/api/v1/admin/observability/requests
/api/v1/admin/observability/requests/{request\_id}
/api/v1/admin/observability/live
/api/v1/admin/observability/anomalies
/api/v1/admin/observability/retention

| Korelasyonlu istek metadata'sı. | | SLO |

/api/v1/admin/slos
/api/v1/admin/slos/evaluate
/api/v1/admin/slos/{slo\_id}/evaluate
/api/v1/admin/slos/{slo\_id}/acknowledge
/api/v1/admin/slos/{slo\_id}/timeline

| Hedef tanımları, değerlendirilmiş durum ve alarm zaman çizelgesi. | | Audit | `/api/v1/admin/audits/` | Değiştirilemez yönetim kayıtları; kullanıcı access JWT'si gerektirir. | Tablo başlangıç noktasıdır, OpenAPI'nin yerine geçmez. Bazı kaynak aileleri generated path tanımlarında görülen nested veya gateway-scoped kimlikler kullanır. ## Request kuralları Varsayılan request/response biçimi JSON'dır: ```bash curl -fsS -X POST \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H 'Content-Type: application/json' \ "$KANGAL_URL/api/v1/admin/gateways/gw-production/services" \ -d '{ "tenant_id": "tenant-acme", "name": "orders", "url": "https://orders.internal" }' | jq ``` Yapılandırma endpoint'leri `Content-Type: application/yaml` veya `?format=yaml` ile YAML da kabul eder; YAML export için `Accept: application/yaml` kullanın. Kaynak oluşturma çoğunlukla `201 Created`, read/update `200 OK`, başarılı delete ise `204 No Content` döndürür. Boş 204 body üzerinde `jq` çalıştırmayın. ```bash status=$(curl -sS -o /tmp/kangal-response.json -w '%{http_code}' \ -X DELETE \ -H "Authorization: Bearer $KANGAL_TOKEN" \ "$KANGAL_URL/api/v1/admin/gateways/gw-production/services/SERVICE_ID") printf 'HTTP %s\n' "$status" test -s /tmp/kangal-response.json && jq . /tmp/kangal-response.json ``` ## Request korelasyonu Otomasyon job'ı veya destek kaydı için kalıcı bir `X-Request-ID` gönderin. Kangal seçilen kimliği `X-Request-ID` olarak döndürür ve route desteklediğinde request context içinde kullanır. ```bash curl -i \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H 'X-Request-ID: change-1842-export' \ "$KANGAL_URL/api/v1/admin/config/export?tenant_id=tenant-acme" ``` Request ID içine credential veya kişisel veri koymayın; log ve audit bağlamında görünebilir. ## Tenant seçimi Tenant-aware endpoint'ler çoğunlukla query veya request body içinde `tenant_id` kabul eder. Davranış route ailesine göre değişir: * Observability ve SLO route'ları caller tenant'ını çözer ve normal admin'in cross-tenant isteğini reddeder. * Normal admin'in audit sorgusu kendi tenant'ına zorlanır; super admin global sorgu yapabilir veya tenant filtreleyebilir. * Yapılandırma endpoint'leri açık tenant değeri kullanır; sync query/body uyuşmazlığını reddeder. Tenant-scoped credential kullanın ve iki değeri de hedef tenant ile eşleştirin. * Tenant atanmamış super admin, tenant-scoped observability/SLO işleminde açık tenant vermelidir. Tenant'ı kaynak adından çıkarmayın. Sabit kimlik kullanın ve write öncesi aktif context'i doğrulayın. ## Endpoint şemasını keşfetme Sürümlü Admin API operasyonlarını listeleyin: ```bash jq -r ' .paths | to_entries[] | select(.key | startswith("/api/v1/admin/")) | .key as $path | .value | to_entries[] | "\(.key | ascii_upcase) \($path)" ' kangal-openapi.json | sort ``` Tek operation ve request body'yi inceleyin: ```bash jq '.paths["/api/v1/admin/config/sync"].post' kangal-openapi.json ``` OpenAPI referans şemaları `.components.schemas` altındadır. Başka bir route ailesinden alan adı tahmin etmek yerine operation'ın verdiği `$ref` şemasını çözün. ## Güvenli otomasyon ```bash set -euo pipefail request_id="deploy-${CI_PIPELINE_ID:-manual}-$(date +%s)" response=$(mktemp) headers=$(mktemp) code=$(curl -sS \ --connect-timeout 5 \ --max-time 30 \ --retry 2 \ --retry-connrefused \ -D "$headers" \ -o "$response" \ -w '%{http_code}' \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H "X-Request-ID: $request_id" \ "$KANGAL_URL/api/v1/admin/gateways?tenant_id=$TENANT_ID") if (( code < 200 || code >= 300 )); then printf 'Kangal isteği başarısız: HTTP %s, request_id=%s\n' "$code" "$request_id" >&2 jq . "$response" 2>/dev/null || cat "$response" >&2 exit 1 fi jq . "$response" ``` Read ve connection establishment hatalarını sınırlı biçimde tekrar deneyin. Timeout olan write'ı, işlemin idempotent olduğunu bilmeden veya canlı state'i kontrol etmeden otomatik tekrarlamayın; yapılandırma import'ı kısmen uygulanmış olabilir. ## Health ve metrikler ```bash curl -fsS "$KANGAL_URL/health" | jq curl -fsS "$KANGAL_URL/ready" | jq curl -fsS "$KANGAL_URL/metrics" | head ``` `/metrics` uygulama bearer-token dependency'sine sahip değildir ve network policy ile korunmalıdır. Health endpoint'leri process/readiness durumunu gösterir; tek bir tenant yapılandırmasının doğru olduğunu kanıtlamaz. Write sonrası kaynak read ve route smoke test yapın. ## Uyumluluk önerileri * Entegrasyonları `/api/v1` sürümüne sabitleyin ve istemcileri deployment'taki OpenAPI belgesinden yeniden üretin. * Response'a eklenen yeni alanları tolere edin. * Enum ve validation hatalarını sessizce dönüştürmek yerine sözleşme geri bildirimi olarak ele alın. * Dokümante edilen pagination header'larını okuyun ve `X-Request-ID` değerini loglarda koruyun. * Ortak CRUD ve config işlemleri için ayrı wrapper yazmak yerine repository'nin desteklediği `kangalctl` aracını kullanın. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kangal.dev/tr/admin-api/api-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.