المرجع
واجهة HTTP للحافة
في هذه الصفحة
العنوان الأساسي والمصادقة
https://edge.nanoflags.ioصادِق بمفتاح بيئة واحدة في ترويسة Authorization. ولا تُقارن المفاتيح ورموز الجلسات إلا كبصمات SHA-256، ولا تسجّلها الحافة أبدًا.
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 | نعم | نعم | 403 | 403 |
/v1/stream، /v1/events | نعم | نعم | غير مدعوم | 403 |
/v1/manifest | نعم | نعم | نعم | 403 |
/v1/ci/*، /v1/admin/export | 403 | 403 | نعم | نعم |
/v1/admin/publish، /v1/admin/flags | 403 | 403 | 403 | نعم |
/v1/keys، /healthz | بلا مصادقة | بلا مصادقة | بلا مصادقة | بلا مصادقة |
- تقبل
/v1/streamأيضًا?key=، لمفاتيح العميل فقط (لا يستطيعEventSourceإرسال ترويسات). وتنتهي مثل هذه العناوين في سجلات الطلبات؛ ومفاتيح العميل عامة بطبيعتها، لكن تعامل مع السجلات بما يناسب. - تقبل
/v1/liveالترويسة، أو قائمة البروتوكولات الفرعية لـ WebSocket في المتصفحات؛ ولا تقبل مفتاحًا في العنوان أبدًا. - تستلم مفاتيح العميل عرض العميل: الأعلام الموسومة client-exposed فقط، والشرائح التي تشير إليها تلك الأعلام فقط.
- المفتاح الذي تحقّقت منه الحافة يُخزَّن مؤقتًا حتى 60 ثانية، فقد يستغرق الإلغاء حتى دقيقة ليسري على الطلبات الجديدة (وأطول أثناء تعذّر الوصول إلى خادم NanoFlags الأصلي؛ انظر آخر نسخة سليمة).
الأخطاء
كل خطأ JSON له رمز ثابت code:
{ "error": { "code": "unauthorized", "message": "Unknown or revoked SDK key." } }| الحالة | code | متى |
|---|---|---|
| 400 | invalid_request، invalid_json | الجسم أو ترويسة لا يستوفيان قواعد نقطة النهاية. |
| 401 | unauthorized | مفتاح مفقود أو مشوّه أو مجهول أو ملغى (WWW-Authenticate: Bearer realm="nanoflags"). |
| 403 | forbidden | لا يحق لنوع المفتاح استخدام نقطة النهاية هذه. |
| 404 | not_found، session_not_found | نقطة نهاية مجهولة؛ أو جلسة اختبار مجهولة أو منتهية أو ملغاة. |
| 405 | method_not_allowed | طريقة خاطئة (ترويسة Allow تذكر الصحيحة؛ وHEAD مقبولة بدل GET). |
| 409 | DESTINATION_CHANGED، NO_CHANGES | تسابق في النشر، أو لا يوجد ما يُنشر. |
| 413 | payload_too_large | الجسم يتجاوز حد نقطة النهاية. |
| 422 | CHANGE_REQUIRED، SCENARIOS_REQUIRED، INVALID_STATE، … | رفضته NanoFlags (رموز من قاعدة البيانات بأحرف كبيرة). |
| 426 | upgrade_required | استُدعيت /v1/live دون ترقية WebSocket. |
| 500 | internal_error | خطأ غير متوقع. |
| 503 | origin_unavailable، live_unavailable | لا تستطيع NanoFlags الإجابة ولا توجد نسخة سليمة سابقة؛ أو الاتصال الحي غير متاح. تُضبط Retry-After. ولا يُبلَّغ عن شيء بأنه تمّ ما لم يُسجَّل. |
GET /v1/bundle
الإعداد المنشور لبيئة المفتاح. لمفاتيح SDK فقط.
GET /v1/bundle HTTP/1.1
Host: edge.nanoflags.io
Authorization: Bearer nf_srv_…
If-None-Match: "92574874cee3f91a0a4cc026142e35df-server"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.
{ "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أو الاستطلاع.
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 مع كل نشر:
{
"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= لمفاتيح العميل.
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 حدثًا لكل طلب.
{
"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"
}
]
}{ "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).
GET /v1/session HTTP/1.1
Authorization: Bearer nf_srv_…
X-NanoFlags-Session: nf_ts_…
X-NanoFlags-Service: checkout-api{
"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 دقائق.
{ "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
{ "source": "draft", "commit": "3b1f0c2…", "runUrl": "https://github.com/acme/shop/actions/runs/123" }{
"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دون شيء منشور ← 422INVALID_STATE. وإن تعذّر تسجيل التشغيل يجيب الاستدعاء بـ 503.
PUT /v1/ci/code-refs
{
"repo": "acme/shop",
"commit": "3b1f0c2…",
"refs": [ { "flag": "checkout-v2", "path": "src/cart.ts", "line": 42, "snippet": "if (flags.boolean(\"checkout-v2\", false, ctx)) {" } ]
}{ "stored": 1 }يستبدل المراجع المخزّنة لـ repo. وcommit وsnippet اختياريان؛ وتُقتطع المقتطفات إلى 240 حرفًا.
GET /v1/ci/published
النسخة المنشورة لبيئة المفتاح، لتقييم ما تستلمه حِزم SDK دون امتلاك مفتاح SDK (يستخدمها nanoflags eval --source published).
{ "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
لمفاتيح المدير فقط. ينشر مسودة بيئة المفتاح.
{ "expectedRevision": 12, "note": "enable checkout v2 for staff" }{ "revision": 13, "checksum": "9c41…" }expectedRevisionإلزامي: النسخة التي تعتقد أنها المنشورة الآن. وnote≤ 500 حرف.- 409
DESTINATION_CHANGED(سبقك أحد بالنشر)، و409NO_CHANGES، و422CHANGE_REQUIRED(البيئة تشترط تغييرًا مراجَعًا؛ ولا تستطيع المفاتيح تجاوز المراجعة)، و422SCENARIOS_REQUIRED.
POST /v1/admin/flags
لمفاتيح المدير فقط. ينشئ علمًا في مشروع المفتاح؛ وتبدأ مسودة كل بيئة بقيمة default. لا يُنشر شيء. وهذا ما يستدعيه nanoflags flags create.
{ "key": "new-checkout", "type": "boolean", "default": false, "description": "New checkout flow", "name": "New checkout" }{ "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(المفتاح موجود في المشروع)، و422INVALID_VALUE(القيمة الافتراضية لا تطابق النوع)، و400 لجسم مشوّه.
التواقيع
الحزم المنشورة موقّعة بخوارزمية Ed25519. ويغطي التوقيع (base64url، 64 بايت، دون حشو) بايتات UTF-8 لهذا النص القانوني:
nanoflags-bundle-v1
<environment id>
<revision>
<checksum>
<sha256 hex of the bundle JSON text, exactly as sent>- خذ
X-NanoFlags-Environment-Idمن الترويسات، وrevisionوchecksumمن الجسم (أوenvironmentIdوrevisionوchecksumمن رسالة الاتصال الحي). - احسب بصمة نص الحزمة: في
/v1/bundleالبايتات الخام بين"bundle":والقوس}الأخير في الجسم؛ وفي/v1/liveالنصbundle. لا تُعِد تسلسل JSON (يمكن لجافاسكريبت حساب بصمةJSON.stringify(body.bundle)للجسم المحلَّل، فهو يعيد إنتاج النص نفسه). - اجمع الأسطر الخمسة بـ
\n(دون سطر جديد في النهاية) وتحقّق من التوقيع بالمفتاح من/v1/keysالذي يساويkidفيهX-NanoFlags-Key-Id.
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");/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.
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, … } لفحوص الحياة.