REST API genel bakış

Taban URL: kurulumunuz, örn. https://push.example.com. Tüm uçlar /v1 altında. Gövdeler JSON; doğrulama katıdır ve hatalar hangi alan olduğunu söyler.

Etkileşimli OpenAPI tarayıcısı API'nin kendisinde /docs altında sunulur.

Kimlik doğrulama

Anahtar	Başlık	Önek	Kim için
Sunucu anahtarı	Authorization: Bearer sk_live_<appId>_<secret>	sk_	backend'iniz, CI. Kapsamlarının izin verdiği her şey.
Public anahtar	x-app-key: pk_live_<appId>_<secret>	pk_	SDK'lar. Cihaz kaydet, o cihazın kullanıcısını güncelle.
(yok)	—	—	POST /v1/e/:kind/:msgId — imzalı msgId kimlik bilgisidir.

Uygulama kimliği anahtara gömülüdür; doğrulama tek indexli sorgu artı bcrypt karşılaştırmadır, API_KEY_CACHE_TTL (60 sn) boyunca önbellekte kalır. Sunucu ucunda public anahtar, kapsamdan bağımsız 403 forbidden döner. Anahtarlar Ayarlar › API anahtarları'nda üretilip iptal edilir.

Kapsamlar

Kapsam	Uçlar
subscriptions:write	POST/PATCH/DELETE /v1/subscriptions/*
subscriptions:read	POST /v1/segments/preview
users:read / users:write	GET / PATCH,DELETE /v1/users/*
notifications:send	POST /v1/notifications
campaigns:read	GET /v1/campaigns/:id/stats
campaigns:write	POST /v1/campaigns, /send, /cancel, /experiment/winner

Rate limit'ler

Sabit 60 saniyelik pencereler, API süreci başına:

Kova	Varsayılan	Anahtar
subscribe / rotate	SUBSCRIBE_RATE_LIMIT = 10/dk	istemci IP
/v1/notifications	SEND_RATE_LIMIT = 100/dk	API anahtarı
/v1/e/*	EVENT_RATE_LIMIT = 600/dk	istemci IP

Sınır aşılınca: mesajında beklenecek saniyeyle 429 rate_limited. İstemci IP'si x-forwarded-for (ilk atlama) ya da x-real-ip'den gelir — proxy'nizin birini ayarladığından emin olun.

Hatalar

Her yerde tek şekil:

{
  "error": {
    "code": "invalid_body",
    "message": "notification payload is invalid",
    "details": [
      { "path": "content._default", "message": "_default \"fr\" is not one of: en, tr" },
      { "path": "target", "message": "provide exactly one of externalIds, userIds, subscriptionIds, segment or all" }
    ]
  }
}

Tam kod listesi: Hatalar.

Idempotency

POST /v1/notifications ve POST /v1/campaigns Idempotency-Key (≤ 255 karakter) kabul eder; 24 saat içindeki tekrarlar Idempotent-Replayed: true ile ilk yanıtı döner. Ayrıntı: Idempotency.

Erişilebilirlik

• GET /health → 200 {"status":"ok","db":"ready"} ya da MongoDB ulaşılamazken 503.
• Mongo kapalıyken her veri ucu kuyruğa almak yerine 503 database_unavailable döner.
• Redis olmadan API hiç başlamaz.

Uç dizini

Metot ve yol	Anahtar	Kapsam	Sayfa
POST /v1/subscriptions	pk / sk	subscriptions:write	Abonelikler
PATCH /v1/subscriptions/:id	pk / sk	subscriptions:write
POST /v1/subscriptions/:id/login	pk / sk	subscriptions:write
POST /v1/subscriptions/:id/logout	pk / sk	subscriptions:write
PATCH ya da POST /v1/subscriptions/:id/user	pk / sk	subscriptions:write
DELETE /v1/subscriptions/:id	pk / sk	subscriptions:write
POST /v1/subscriptions/rotate	pk / sk	subscriptions:write
POST /v1/subscriptions/:id/session	pk / sk	subscriptions:write
GET /v1/users/:id · /by-external-id/:externalId	sk	users:read	Kullanıcılar
PATCH /v1/users/:id · /by-external-id/:externalId	sk	users:write
DELETE /v1/users/:id · /by-external-id/:externalId	sk	users:write
POST /v1/notifications	sk	notifications:send	Bildirimler
POST /v1/campaigns	sk	campaigns:write	Kampanyalar
POST /v1/campaigns/:id/send · /cancel	sk	campaigns:write
POST /v1/campaigns/:id/experiment/winner	sk	campaigns:write
GET /v1/campaigns/:id/stats	sk	campaigns:read
POST /v1/segments/preview	sk	subscriptions:read	Segmentler
GET /v1/segments · GET /v1/segments/:id · POST /v1/segments/:id/count	sk	subscriptions:read
POST /v1/segments · PUT · DELETE /v1/segments/:id	sk	campaigns:write
GET /v1/templates · GET /v1/templates/:id	sk	campaigns:read	Şablonlar
POST /v1/templates · PUT · DELETE /v1/templates/:id	sk	campaigns:write
POST /v1/e/:kind/:msgId	yok	—	Olaylar
GET /health	yok	—
/v1/admin/*	ADMIN_API_TOKEN	—	yalnızca panel; ayarsızken 404

Gelenekler

• Id'ler string olarak 24 hex MongoDB ObjectId'dir.
• Zaman damgaları ISO 8601 UTC'dir.
• PATCH gövdeleri kısmidir ve en az bir alan içermelidir.
• Admin yüzeyi (/v1/admin) public API değildir: panel için vardır, paylaşılan token ister ve kararlılık sözü yoktur.