انتقل إلى المحتوى
NanoFlags
ابدأ مجانًا

المرجع

واجهة HTTP للحافة

تقدّم الحافة الإعداد المنشور إلى حِزم SDK، وتوفّر واجهة CI والمدير التي تستخدمها أداة سطر الأوامر. وتقيّم حِزم SDK محليًا، فلا تقع الحافة على مسار التقييم أبدًا. استخدم الـ SDK حيثما أمكن؛ فهذه الصفحة للغات الأخرى وللتشخيص ولأدواتك الخاصة.

العنوان الأساسي والمصادقة

text
https://edge.nanoflags.io

صادِق بمفتاح بيئة واحدة في ترويسة Authorization. ولا تُقارن المفاتيح ورموز الجلسات إلا كبصمات SHA-256، ولا تسجّلها الحافة أبدًا.

sh
curl -H "Authorization: Bearer $NANOFLAGS_SDK_KEY" https://edge.nanoflags.io/v1/manifest
نقطة النهايةالعميل nf_pub_الخادم nf_srv_CI nf_ci_المدير nf_adm_
/v1/bundle، /v1/live، /v1/sessionنعمنعم403403
/v1/stream، /v1/eventsنعمنعمغير مدعوم403
/v1/manifestنعمنعمنعم403
/v1/ci/*، /v1/admin/export403403نعمنعم
/v1/admin/publish، /v1/admin/flags403403403نعم
/v1/keys، /healthzبلا مصادقةبلا مصادقةبلا مصادقةبلا مصادقة
  • تقبل /v1/stream أيضًا ?key=، لمفاتيح العميل فقط (لا يستطيع EventSource إرسال ترويسات). وتنتهي مثل هذه العناوين في سجلات الطلبات؛ ومفاتيح العميل عامة بطبيعتها، لكن تعامل مع السجلات بما يناسب.
  • تقبل /v1/live الترويسة، أو قائمة البروتوكولات الفرعية لـ WebSocket في المتصفحات؛ ولا تقبل مفتاحًا في العنوان أبدًا.
  • تستلم مفاتيح العميل عرض العميل: الأعلام الموسومة client-exposed فقط، والشرائح التي تشير إليها تلك الأعلام فقط.
  • المفتاح الذي تحقّقت منه الحافة يُخزَّن مؤقتًا حتى 60 ثانية، فقد يستغرق الإلغاء حتى دقيقة ليسري على الطلبات الجديدة (وأطول أثناء تعذّر الوصول إلى خادم NanoFlags الأصلي؛ انظر آخر نسخة سليمة).

الأخطاء

كل خطأ JSON له رمز ثابت code:

json
{ "error": { "code": "unauthorized", "message": "Unknown or revoked SDK key." } }
الحالةcodeمتى
400invalid_request، invalid_jsonالجسم أو ترويسة لا يستوفيان قواعد نقطة النهاية.
401unauthorizedمفتاح مفقود أو مشوّه أو مجهول أو ملغى (WWW-Authenticate: Bearer realm="nanoflags").
403forbiddenلا يحق لنوع المفتاح استخدام نقطة النهاية هذه.
404not_found، session_not_foundنقطة نهاية مجهولة؛ أو جلسة اختبار مجهولة أو منتهية أو ملغاة.
405method_not_allowedطريقة خاطئة (ترويسة Allow تذكر الصحيحة؛ وHEAD مقبولة بدل GET).
409DESTINATION_CHANGED، NO_CHANGESتسابق في النشر، أو لا يوجد ما يُنشر.
413payload_too_largeالجسم يتجاوز حد نقطة النهاية.
422CHANGE_REQUIRED، SCENARIOS_REQUIRED، INVALID_STATE، …رفضته NanoFlags (رموز من قاعدة البيانات بأحرف كبيرة).
426upgrade_requiredاستُدعيت /v1/live دون ترقية WebSocket.
500internal_errorخطأ غير متوقع.
503origin_unavailable، live_unavailableلا تستطيع NanoFlags الإجابة ولا توجد نسخة سليمة سابقة؛ أو الاتصال الحي غير متاح. تُضبط Retry-After. ولا يُبلَّغ عن شيء بأنه تمّ ما لم يُسجَّل.

GET /v1/bundle

الإعداد المنشور لبيئة المفتاح. لمفاتيح SDK فقط.

request
GET /v1/bundle HTTP/1.1
Host: edge.nanoflags.io
Authorization: Bearer nf_srv_…
If-None-Match: "92574874cee3f91a0a4cc026142e35df-server"
response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Vary: Authorization
ETag: "92574874cee3f91a0a4cc026142e35df-server"
X-NanoFlags-Signed: true
X-NanoFlags-Environment-Id: 18f1768e-840b-4a82-a9ab-437008b88ca9
X-NanoFlags-Key-Id: k1
X-NanoFlags-Signature: 31mqy6-tV4rRk1cf…ERAw

{"revision":108,"checksum":"92574874cee3f91a0a4cc026142e35df","bundle":{"schema":1,"project":"commerce","environment":"staging","revision":108,"flags":{…},"segments":{…}}}
  • X-NanoFlags-Signature وX-NanoFlags-Key-Id لا يوجدان إلا مع X-NanoFlags-Signed: true. وX-NanoFlags-Environment-Id موجود متى كانت البيئة معروفة، حتى في الإجابات غير الموقّعة.
  • بعد النشر مباشرة، وإلى أن يلحق التوقيع، قد تجيب الحافة من قاعدة البيانات مع X-NanoFlags-Signed: false.
  • الأخطاء: 401، و403 (مفتاح CI أو مدير)، و503 origin_unavailable.

تحتوي الحزمة على schema وproject وenvironment وrevision وflags (مفتاح العلم ← { type, enabled, rules, default, off, clientExposed }) وsegments. انظر كيف يُقيَّم العلم.

GET /v1/manifest

النسخة الحالية دون الحزمة. لمفاتيح SDK وCI.

200
{ "revision": 108, "checksum": "92574874cee3f91a0a4cc026142e35df", "environment": "staging" }

GET /v1/live ‏(WebSocket)

تدفع كل نسخة منشورة، والحزمة الموقّعة داخل الرسالة. لمفاتيح SDK.

الاتصال

  • الخوادم: Authorization: Bearer <sdk key> في طلب الترقية.
  • المتصفحات: البروتوكولات الفرعية ["nanoflags.v1", "key.<sdk key>"]؛ ويجيب الخادم بـ nanoflags.v1.
  • الأخطاء قبل الترقية: 401 (لا مفتاح أو مفتاح مجهول، أو قائمة بروتوكولات مشوّهة، أو مفتاح في العنوان)، و403 (مفتاح CI أو مدير)، و426 (ليس طلب WebSocket)، و503 live_unavailable (بلوغ حد الاتصالات، أو التحديثات الحيّة غير متاحة): ارجع إلى /v1/stream أو الاستطلاع.
browser
const ws = new WebSocket("wss://edge.nanoflags.io/v1/live", ["nanoflags.v1", "key.nf_pub_…"]);
ws.onmessage = (e) => {
  if (e.data === "pong") return;
  const m = JSON.parse(e.data);           // { t: "hello" | "rev", revision, bundle, … }
  if (m.bundle) apply(JSON.parse(m.bundle), m);
};
setInterval(() => ws.send("ping"), 30_000);

الرسائل

من الخادم إلى العميل، نص JSON. ‏hello عند الاتصال (الحالة الحالية، فيلحق العميل المعاود للاتصال برسالة واحدة)، وrev مع كل نشر:

json
{
  "t": "rev",
  "revision": 109,
  "checksum": "0b6c2a…",
  "signature": "base64url Ed25519 signature",
  "kid": "k1",
  "environmentId": "18f1768e-840b-4a82-a9ab-437008b88ca9",
  "bundle": "{\"schema\":1,\"project\":\"commerce\",…}",
  "committedAt": 1762770000123,
  "sentAt": 1762770000301
}
  • bundle نص: نص JSON الموقّع بالضبط. تحقّق منه كما في التواقيع باستخدام environmentId وrevision وchecksum وkid وsignature؛ وتستلم اتصالات مفاتيح العميل عرض العميل وتوقيعه.
  • committedAt وsentAt بالمللي ثانية منذ epoch. وقد يكون committedAt (وقت الالتزام في قاعدة البيانات) null.
  • البيئة التي لم يُنشر فيها شيء تحيّي بـ { "t": "hello", "revision": 0, "bundle": null, … }.
  • من العميل إلى الخادم: النص ping، ويُجاب بـ pong.
  • يُصادَق على الاتصال عند فتحه. والاتصال الأقدم من ساعتين يُغلق بالرمز 4001 (reauthenticate) عند النشر التالي بدل أن يستلمه؛ فأعد الاتصال. ويستبدل الـ SDK اتصاله نحو كل 50 دقيقة.
  • عند حذف البيئة أو مشروعها تُغلق الاتصالات المفتوحة بالرمز 4004 (environment_deleted). لا تُعد الاتصال؛ فالمفتاح لم يعد يعمل.
  • تقبل البيئة حتى 10,000 اتصال حي؛ وبعدها تجيب الحافة بـ 503. والنسخ الأكبر من نحو 1.9 MB لا تُدفع؛ ويحصل عليها العملاء بالاستطلاع.

GET /v1/stream ‏(SSE)

أحداث من الخادم لا تحمل إلا النسخة؛ واجلب الحزمة بنفسك (بشكل مشروط). لمفاتيح SDK؛ و?key= لمفاتيح العميل.

text/event-stream
retry: 3000
event: revision
data: {"revision":108,"checksum":"92574874cee3f91a0a4cc026142e35df"}

: hb

event: revision
data: {"revision":109,"checksum":"0b6c2a…"}
  • يُرسل أول حدث revision فورًا، والتالية عند التغيير. وأسطر التعليق (: hb) نبضات حياة. ويغلق الخادم المجرى بعد نحو 5 دقائق؛ فأعد الاتصال.
  • يُلاحظ المفتاح الملغى عند إعادة اتصال المجرى. وقد ينتهي المجرى أيضًا بـ event: revoked.

POST /v1/events

بلاغ خدمة مع تقييمات مأخوذة كعيّنات. لمفاتيح SDK. بحد أقصى 64 KB و50 حدثًا لكل طلب.

request body
{
  "service": "checkout-api",
  "sdk": "js/0.3.0",
  "revision": 108,
  "events": [
    {
      "flagKey": "checkout-v2",
      "value": true,
      "reason": "rule_match",
      "ruleIndex": 0,
      "revision": 108,
      "context": { "key": "string", "region": "string" },
      "at": "2026-11-10T09:30:00.000Z"
    }
  ]
}
202
{ "accepted": 1, "capped": false }
الحقلالقواعد
serviceإلزامي، من 1 إلى 60 حرفًا. تُعلنه العملية عن نفسها.
sdkنص إلزامي، 40 حرفًا على الأكثر.
revisionإلزامي، النسخة التي حمّلتها العملية (عدد صحيح غير سالب).
events[].flagKeyإلزامي، من 1 إلى 63 حرفًا.
value، reason (≤ 30)، ruleIndex، revisionاختيارية.
contextكائن اختياري. ما ترسله يُخزَّن: أخفِ البيانات قبل الإرسال.
requestId (≤ 64)، at (ISO 8601)اختيارية.
sessionIdمعرّف جلسة اختبار اختياري (UUID) من /v1/session، لا الرمز أبدًا.
  • يُسجَّل بلاغ الخدمة مع كل طلب مقبول. وتُخزَّن الأحداث حتى بلوغ الحد اليومي للبيئة؛ عندها capped: true ولا تُخزَّن الأحداث حتى اليوم التالي (UTC). انظر الحد اليومي للأحداث.
  • القياس بأفضل جهد: عند 503 أسقط الدفعة بدل إعادة المحاولة.

GET /v1/session

يحلّ جلسة اختبار. لمفاتيح SDK. لا يُخزَّن مؤقتًا أبدًا (Cache-Control: no-store).

request
GET /v1/session HTTP/1.1
Authorization: Bearer nf_srv_…
X-NanoFlags-Session: nf_ts_…
X-NanoFlags-Service: checkout-api
200
{
  "id": "6d0f…",
  "checksum": "…",
  "source": "draft",
  "revision": null,
  "context": { "region": "DE" },
  "expires_at": "2026-11-10T12:00:00Z",
  "bundle": { "schema": 1, "flags": { … }, "segments": { … } }
}

‏400 دون ترويسة الجلسة (أو اسم خدمة يتجاوز 60 حرفًا)، و401 لمفتاح مجهول، و403 لمفتاح CI أو مدير، و404 session_not_found (جلسة مجهولة أو منتهية أو ملغاة، أو هذه الخدمة ليست جزءًا من الجلسة)، و503 origin_unavailable. وحزم الجلسات غير موقّعة.

GET /v1/keys

مفاتيح التوقيع العامة كقائمة بأسلوب JWKS، دون مصادقة، وقابلة للتخزين المؤقت 5 دقائق.

200
{ "keys": [ { "kty": "OKP", "crv": "Ed25519", "x": "wQu1EsaE-yTjqpUbibGyBrajy3IiRb7LyaiqeYRxG4U", "kid": "k1", "alg": "EdDSA", "use": "sig", "status": "active" } ] }
  • status هي active للمفتاح الذي يوقّع الحزم الجديدة، أو retiring لمفتاح سابق يبقى مدرجًا أثناء التدوير كي تجتاز الحزم الموقّعة به التحقق. اختر المفتاح حسب kid أيًّا كانت حالته.
  • كل حزمة تحمل أيضًا engine، أي إصدار محرك التقييم الذي تحتاجه. والعميل الذي لا يدعم ذلك الإصدار ينبغي أن يُبقي إعداده السابق.

واجهة CI

لمفاتيح CI والمدير. وتحصل مفاتيح SDK على 403.

POST /v1/ci/scenarios/run

request body (all optional, ≤ 16 KB)
{ "source": "draft", "commit": "3b1f0c2…", "runUrl": "https://github.com/acme/shop/actions/runs/123" }
200
{
  "source": "draft",
  "checksum": "5e0d…",
  "publishedRevision": 12,
  "passed": 1,
  "failed": 1,
  "results": [
    { "id": "…", "name": "US signed-in gets v2", "flag": "checkout-v2", "expected": true, "actual": true, "passed": true, "reason": "rule_match" },
    { "id": "…", "name": "EU stays on v1", "flag": "checkout-v2", "expected": false, "actual": true, "passed": false, "reason": "rule_match" }
  ]
}
  • source: ‏draft (الافتراضي) أو revision. وcommit ≤ 64 حرفًا؛ وrunUrl بـ http(s) و≤ 300 حرف.
  • HTTP 200 حتى عند فشل السيناريوهات: افحص failed. والمقارنة مساواة JSON عميقة؛ والعلم المفقود (flag_not_found) أو خطأ التقييم لا ينجح أبدًا.
  • checksum هي بصمة المسودة مع draft وبصمة النسخة المنشورة مع revision. وsource: revision دون شيء منشور ← 422 INVALID_STATE. وإن تعذّر تسجيل التشغيل يجيب الاستدعاء بـ 503.

PUT /v1/ci/code-refs

request body (≤ 4 MB, ≤ 5,000 refs)
{
  "repo": "acme/shop",
  "commit": "3b1f0c2…",
  "refs": [ { "flag": "checkout-v2", "path": "src/cart.ts", "line": 42, "snippet": "if (flags.boolean(\"checkout-v2\", false, ctx)) {" } ]
}
200
{ "stored": 1 }

يستبدل المراجع المخزّنة لـ repo. وcommit وsnippet اختياريان؛ وتُقتطع المقتطفات إلى 240 حرفًا.

GET /v1/ci/published

النسخة المنشورة لبيئة المفتاح، لتقييم ما تستلمه حِزم SDK دون امتلاك مفتاح SDK (يستخدمها nanoflags eval --source published).

200
{ "revision": 108, "checksum": "92574874cee3f91a0a4cc026142e35df", "bundle": { "schema": 1, "flags": { … }, "segments": { … } } }

الحزمة كاملة (كل الأعلام) وغير موقّعة: التواقيع تخص /v1/bundle. ولا شيء منشور بعد ← 422 INVALID_STATE.

واجهة المدير

GET /v1/admin/export

لمفاتيح CI والمدير. المشروع كـ JSON: الأعلام (مع permanent وarchived …)، والشرائح، والبيئات، ومسودة كل بيئة. وهذا ما يطبعه nanoflags export.

POST /v1/admin/publish

لمفاتيح المدير فقط. ينشر مسودة بيئة المفتاح.

request body
{ "expectedRevision": 12, "note": "enable checkout v2 for staff" }
200
{ "revision": 13, "checksum": "9c41…" }
  • expectedRevision إلزامي: النسخة التي تعتقد أنها المنشورة الآن. وnote ≤ 500 حرف.
  • 409 DESTINATION_CHANGED (سبقك أحد بالنشر)، و409 NO_CHANGES، و422 CHANGE_REQUIRED (البيئة تشترط تغييرًا مراجَعًا؛ ولا تستطيع المفاتيح تجاوز المراجعة)، و422 SCENARIOS_REQUIRED.

POST /v1/admin/flags

لمفاتيح المدير فقط. ينشئ علمًا في مشروع المفتاح؛ وتبدأ مسودة كل بيئة بقيمة default. لا يُنشر شيء. وهذا ما يستدعيه nanoflags flags create.

request body
{ "key": "new-checkout", "type": "boolean", "default": false, "description": "New checkout flow", "name": "New checkout" }
201
{ "id": "…", "key": "new-checkout", "name": "New checkout", "type": "boolean", "default": false, "environments": ["development", "staging", "production"] }
  • key وtype (boolean أو string أو number أو json) وdefault إلزامية؛ وdescription ≤ 2000 وname ≤ 120 حرفًا (افتراضيًا: المفتاح).
  • 409 CONFLICT (المفتاح موجود في المشروع)، و422 INVALID_VALUE (القيمة الافتراضية لا تطابق النوع)، و400 لجسم مشوّه.

التواقيع

الحزم المنشورة موقّعة بخوارزمية Ed25519. ويغطي التوقيع (base64url، ‏64 بايت، دون حشو) بايتات UTF-8 لهذا النص القانوني:

canonical string
nanoflags-bundle-v1
<environment id>
<revision>
<checksum>
<sha256 hex of the bundle JSON text, exactly as sent>
  1. خذ X-NanoFlags-Environment-Id من الترويسات، وrevision وchecksum من الجسم (أو environmentId وrevision وchecksum من رسالة الاتصال الحي).
  2. احسب بصمة نص الحزمة: في /v1/bundle البايتات الخام بين "bundle": والقوس } الأخير في الجسم؛ وفي /v1/live النص bundle. لا تُعِد تسلسل JSON (يمكن لجافاسكريبت حساب بصمة JSON.stringify(body.bundle) للجسم المحلَّل، فهو يعيد إنتاج النص نفسه).
  3. اجمع الأسطر الخمسة بـ \n (دون سطر جديد في النهاية) وتحقّق من التوقيع بالمفتاح من /v1/keys الذي يساوي kid فيه X-NanoFlags-Key-Id.
verify.mjs (Node 20+)
import { createHash, createPublicKey, verify } from "node:crypto";

const base = "https://edge.nanoflags.io";
const res = await fetch(`${base}/v1/bundle`, { headers: { Authorization: `Bearer ${process.env.NANOFLAGS_SDK_KEY}` } });
const text = await res.text(); // keep the raw text: the signature covers the bundle bytes exactly as sent

if (res.headers.get("x-nanoflags-signed") !== "true") throw new Error("unsigned bundle");
const { revision, checksum } = JSON.parse(text);
const marker = '"bundle":';
const bundleText = text.slice(text.indexOf(marker) + marker.length, text.lastIndexOf("}"));
const canonical = [
  "nanoflags-bundle-v1",
  res.headers.get("x-nanoflags-environment-id"),
  revision,
  checksum,
  createHash("sha256").update(bundleText, "utf8").digest("hex"),
].join("\n");

const { keys } = await (await fetch(`${base}/v1/keys`)).json(); // or pin the key in your build
const jwk = keys.find((k) => k.kid === res.headers.get("x-nanoflags-key-id"));
const ok = verify(
  null,
  Buffer.from(canonical, "utf8"),
  createPublicKey({ key: { kty: jwk.kty, crv: jwk.crv, x: jwk.x }, format: "jwk" }),
  Buffer.from(res.headers.get("x-nanoflags-signature"), "base64url"),
);
console.log(ok ? `r${revision} verified` : "signature mismatch");
ما يثبته التوقيع وما لا يثبته
التوقيع الصالح يثبت أن الحزمة هي بالضبط ما نشرته NanoFlags لتلك البيئة وتلك النسخة. ولا يقول شيئًا عن الحداثة: فهو لا يمنع أحدًا من تقديم نسخة موقّعة أقدم أو حجب التحديثات. والمفاتيح المجلوبة من /v1/keys موثوقة بقدر الحافة التي قدّمتها فقط؛ فثبّت المفتاح العام في البناء إن كانت الحافة ضمن نموذج التهديد لديك.

ETag و304

تجيب /v1/bundle بـ ETag: "<checksum>-<kind>" (وkind هي server أو client، لأن العرضين مختلفان). أرسلها في If-None-Match؛ وعندما لا يتغير شيء تكون الإجابة 304 Not Modified دون جسم، مع ترويسات X-NanoFlags-* نفسها. وتُقبل المحدّدات الضعيفة (W/) و*.

إجابات آخر نسخة سليمة

إن تعذّر الوصول إلى خادم NanoFlags الأصلي أو كان بطيئًا، تواصل الحافة تقديم آخر إعداد لديها للمفاتيح التي تحقّقت منها خلال آخر 24 ساعة، وتسم الإجابة بـ X-NanoFlags-Stale: true وX-NanoFlags-Stored-At. ومن دون أي نسخة مخزّنة تجيب بـ 503. لذا قد يواصل مفتاح ملغى استلام الإعداد أثناء تعطّل الخادم الأصلي حتى 24 ساعة. ولا يُعامل كإلغاء إلا رد صريح من الخادم الأصلي بأن «المفتاح مجهول»؛ أمّا خطأ الخادم الأصلي فلا يُعامل كذلك أبدًا.

CORS

كل نقاط النهاية تدعم CORS لأي مصدر. وطلبات OPTIONS التمهيدية تُجاب بـ 204.

http
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, If-None-Match, Cache-Control, Last-Event-ID, X-NanoFlags-Session, X-NanoFlags-Service
Access-Control-Expose-Headers: ETag, X-NanoFlags-Stale, X-NanoFlags-Stored-At, X-NanoFlags-Signed, X-NanoFlags-Signature, X-NanoFlags-Key-Id, X-NanoFlags-Environment-Id
Access-Control-Max-Age: 86400

لا تنتمي إلى شيفرة المتصفح إلا مفاتيح العميل. وتجيب GET /healthz بـ { "ok": true, … } لفحوص الحياة.