API بوابة التحديثات
توفر بوابة التحديثات (Updates Portal) واجهة برمجة تطبيقات JSON عامة ومحدودة لتتمكن من استطلاع الحالة، وجلب إدخالات سجل التغييرات، ومتابعة خارطة الطريق، والتحقق من المشكلات المعروفة من أنظمتك الخاصة. لا يلزم أي مصادقة. تقدم API النصوص باللغة الإنجليزية فقط؛ ويتم تجاهل بادئة اللغة في المسار.
عنوان URL الأساسي
https://updates.foura.ai
حالة الخدمة
GET /api/v1/status
تُرجع الحالة التشغيلية المباشرة لكل خدمة من خدمات FourA، بالإضافة إلى الحوادث النشطة والأخيرة. يتم التخزين المؤقت في جانب الخادم لمدة 15 ثانية، لذا فإن الاستقصاء بمعدل أعلى من ذلك يُرجع نفس البيانات.
curl https://updates.foura.ai/api/v1/status
{
"overall": "operational",
"updated_at": "2026-05-19T12:00:00.000Z",
"services": [
{
"slug": "api-gateway",
"name": "API Gateway",
"description": "...",
"status": "operational",
"daily": [
{ "date": "2026-05-19", "status": "operational", "major_outage_minutes": 0, "partial_outage_minutes": 0, "degraded_minutes": 0, "internal_degraded_minutes": 0 }
]
}
],
"active_incidents": [],
"recent_incidents": [
{ "id": 12, "service_slug": "api-gateway", "service_name": "API Gateway", "impact": "minor", "title": "API Gateway: Degraded Performance", "status": "resolved", "started_at": "...", "resolved_at": "...", "duration_seconds": 30 }
]
}
| حقل المستوى الأعلى | النوع | الوصف |
|---|---|---|
overall |
string | operational إذا كانت جميع الخدمات سليمة، وإلا فإحدى قيم حالة الخدمة |
updated_at |
string | وقت إنشاء بيانات الحالة، بتنسيق ISO 8601 مع لاحقة Z |
services |
array | إدخال واحد لكل خدمة خاضعة للمراقبة يتضمن slug، وname، وdescription، وstatus الحالية، وسجل daily (حتى 90 يوما) |
active_incidents |
array | الحوادث المفتوحة حاليا |
recent_incidents |
array | الحوادث التي تم حلها خلال آخر 14 يوما، ويحتوي كل منها على id، وservice_slug، وservice_name، وimpact، وtitle، وstatus، وstarted_at، وresolved_at، وduration_seconds |
قيم status للخدمة: operational، وdegraded، وpartial_outage، وmajor_outage، وmaintenance. يمكن أن يحمل إدخال daily أيضا القيمة no_data، وذلك لأي يوم لا توجد به بيانات مسجلة. يحتسب internal_degraded_minutes الوقت الذي لم يشهد أي تأثير على العملاء.
قيم impact للحادثة: minor (أداء منخفض)، وmajor (انقطاع جزئي)، وcritical (انقطاع في الخدمة).
نمط الاستقصاء
استخدم هذا الـ endpoint لربط حالة FourA بلوحة التحكم أو نظام التنبيه الخاص بك.
عند تعذر جلب بيانات الحالة، يستجيب الـ endpoint برمز 502 مع {"error": "Monitor unreachable"}. تعامل مع ذلك على أنه حالة غير معروفة بدلا من اعتباره عطلا، وأعد المحاولة في دورة الاستقصاء التالية.
import requests
def check_foura():
r = requests.get("https://updates.foura.ai/api/v1/status", timeout=5)
r.raise_for_status() # raises on the 502 "Monitor unreachable" answer: retry next poll
data = r.json()
if data["overall"] != "operational":
# Page on-call, post to Slack, flip a feature flag, etc.
for svc in data["services"]:
if svc["status"] != "operational":
print(f"{svc['name']}: {svc['status']}")
return data
يعيد GET /api/status القديم 410 Gone ويوجه المتصلين إلى هنا.
سجل التغييرات
GET /api/changelog
يعيد إدخالات سجل التغييرات المنشورة بترتيب زمني عكسي.
curl "https://updates.foura.ai/api/changelog?limit=20"
معلمات الاستعلام:
| المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
page |
integer | 1 | رقم الصفحة بفهرسة تبدأ من 1 |
limit |
integer | 20 | عدد الإدخالات لكل صفحة (الحد الأقصى 50) |
category |
string | - | التصفية حسب new، أو improved، أو fixed |
{
"entries": [
{
"id": 42,
"title": "...",
"body": "Markdown body",
"category": "new",
"tags": "[\"api\",\"dashboard\"]",
"published": 1,
"published_at": "2026-05-19T12:00:00Z",
"created_at": "2026-05-19 11:42:08",
"updated_at": "2026-05-19 11:44:31"
}
],
"total": 137,
"page": 1,
"limit": 20
}
| الحقل | النوع | الوصف |
|---|---|---|
id |
integer | معرف المدخلة |
title |
string | عنوان المدخلة |
body |
string | نص Markdown |
category |
string | new، أو improved، أو fixed |
tags |
string | مصفوفة JSON ترمّز كسلسلة نصية. قم بتحليلها قبل الاستخدام: json.loads(entry["tags"]). |
published |
integer | دائمًا 1 هنا. لا يعيد الـ endpoint سوى المدخلات المنشورة. |
published_at |
string | بتنسيق ISO 8601 مع لاحقة Z |
created_at |
string | YYYY-MM-DD HH:MM:SS، بتوقيت UTC، بدون محدد للمنطقة الزمنية |
updated_at |
string | نفس تنسيق created_at |
يختلف تنسيقا الطابع الزمني عن قصد: published_at هو تاريخ التحرير ويتضمن منطقة زمنية، بينما created_at و updated_at هما طابعا التخزين الزمني. كلاهما بتوقيت UTC. إذا افترضت أداة التحليل تنسيقًا واحدًا لجميع الحقول الثلاثة، فستفشل مع الحقلين الآخرين.
RSS
ينشر أيضًا سجل التغييرات الكامل (أحدث 30 مدخلة) بتنسيق RSS على:
https://updates.foura.ai/rss
اشترك عبر Feedly أو Miniflux أو Thunderbird أو أي قارئ آخر. يطابق نص الخلاصة محتوى changelog، بما في ذلك markdown المعروض كـ HTML.
خريطة الطريق
GET /api/roadmap
يُرجع كل عنصر منشور في خريطة الطريق، مرتبا حسب عدد الأصوات ثم وقت الإنشاء.
curl https://updates.foura.ai/api/roadmap
{
"items": [
{
"id": 12,
"title": "...",
"description": "...",
"status": "planned",
"category": "developer-experience",
"votes": 23,
"target_date": "Q3 2026",
"completed_at": null,
"created_at": "2026-03-30 09:32:47"
}
]
}
قيم status للعنصر: planned، in_progress، done، cancelled. تعرض اللوحة على updates.foura.ai/roadmap ثلاثة أعمدة، لذلك فإن العنصر المضبوط على cancelled يصلك عبر هذا الـ endpoint ولا يظهر مطلقًا على الصفحة.
category عبارة عن slug بأحرف صغيرة، وليس التسمية التي تعرضها الصفحة. الـ slugs المستخدمة حاليًا: api، infrastructure، developer-experience، dashboard، billing، analytics، authentication. تعامل مع القائمة على أنها مفتوحة، حيث يمكن لعنصر جديد تقديم slug جديد.
target_date عبارة عن نص حر ("Q3 2026")، وليس تاريخًا. يكون completed_at بقيمة null حتى يتم إطلاق العنصر، ثم يصبح بتنسيق ISO 8601 مع لاحقة Z (2026-09-01T10:15:30.000Z)، وهو نفس تنسيق published_at الخاص بمدخل سجل التغييرات. يستخدم created_at التنسيق YYYY-MM-DD HH:MM:SS بتوقيت UTC. يختلف التنسيقان داخل الكائن الواحد، لذا قم بتحليل كل حقل على حدة.
التصويت
POST /api/roadmap/:id/vote
يقوم بتبديل حالة التصويت على عنصر واحد في خارطة الطريق. عمليات التصويت مجهولة ومرتبطة بعنوان IP الخاص بالمتصل بالإضافة إلى أول 50 حرفًا من User-Agent الخاص به. يؤدي الاستدعاء مرة أخرى إلى إزالة التصويت. يستجيب العنصر غير المعروف أو غير المنشور بـ 404 {"error": "Not found"}.
curl -X POST https://updates.foura.ai/api/roadmap/12/vote
{ "votes": 24, "voted": true }
يُبلّغ voted عن الحالة بعد الاستدعاء: true إذا تمت إضافة تصويتك، وfalse إذا تمت إزالته.
تقتصر نقاط نهاية roadmap، وهي GET /api/roadmap وهذه النقطة، على 30 طلبًا في الدقيقة لكل عنوان IP مصدر. عند تجاوز ذلك، تكون الاستجابة HTTP 429 مع {"error": "Too many votes, slow down"}. تحمل كل استجابة roadmap الترويسات X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset (طابع زمني بتنسيق Unix بالثواني)، حتى تتمكن من إبطاء المعدل قبل الوصول إلى الحد الأقصى.
المشكلات المعروفة
GET /api/issues
تُرجع المشكلات التي يتتبعها فريق دعم FourA.
curl "https://updates.foura.ai/api/issues?tab=open"
معلمات الاستعلام:
| المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
tab |
string | open |
open للمشكلات النشطة، وresolved للمحلولة/المغلقة |
{
"issues": [
{
"id": 5,
"title": "...",
"body": "Markdown description",
"severity": "medium",
"status": "investigating",
"service_id": 3,
"resolution": "",
"opened_at": "2026-05-18T09:00:00Z",
"resolved_at": null,
"service_name": "API"
}
]
}
| الحقل | النوع | الوصف |
|---|---|---|
id |
integer | معرف المشكلة (ID) |
title |
string | ملخص موجز |
body |
string | وصف بتنسيق Markdown |
severity |
string | low، أو medium، أو high، أو critical |
status |
string | open، أو investigating، أو resolved، أو closed |
service_id |
integer or null | المعرف الرقمي للخدمة المتأثرة. null عندما لا تكون المشكلة مرتبطة بخدمة معينة. |
service_name |
string or null | الاسم المعروض للخدمة، تمت معالجته نيابة عنك. اقرأ هذه القيمة بدلا من تعيين service_id يدويا. |
resolution |
string | كيفية حل المشكلة. سلسلة فارغة طالما أن المشكلة ما تزال مفتوحة. |
opened_at |
string | تنسيق ISO 8601 مع لاحقة Z |
resolved_at |
string or null | تنسيق ISO 8601 مع لاحقة Z، وتكون null طالما أن المشكلة مفتوحة |
إن service_id هو مفتاح أجنبي رقمي، وليس الاسم اللطيف (slug) الذي تراه في صفحة الحالة. طابق المشكلات مع الخدمات باستخدام service_name.
حمولة المشكلة عبارة عن قائمة أعمدة ثابتة ولا تتضمن طابعا زمنيا للتعديل. رتب المشكلة أو حدد عمرها الزمني باستخدام opened_at وresolved_at. من بين المجموعات العامة الثلاث، تعيد إدخالات سجل التغييرات فقط updated_at. وتعيد عناصر خارطة الطريق created_at أيضا، بينما لا تعيد المشكلات أيا منهما.
تبويب resolved يعيد آخر 30 مشكلة تم حلها ويتوقف عندها. تبويب open يعيد جميع المشكلات.
ملاحظات
- جميع نقاط النهاية (endpoints) عامة ولا تتطلب مفتاح API. تقتصر نقاط نهاية خارطة الطريق على 30 طلبا في الدقيقة لكل عنوان IP مصدر، بينما لا تخضع النقاط الأخرى لأي rate limit خاص بها حاليا، لذا تجنب استقصاء الحالة بمعدل يتجاوز ما يبرره التخزين المؤقت ومدته 15 ثانية.
- تأتي الاستجابات بتنسيق JSON عبر HTTPS. لا تقبل خارطة الطريق والمشكلات معاملات تقسيم الصفحات (paging). القيد الوحيد هو
?tab=resolvedعلى المشكلات، حيث يعيد 30 صفا. - للحصول على نسخ نصية مجردة أو بتنسيق HTML الأولي من سجل التغييرات، استخدم خلاصة
/rssبدلا من/api/changelog.
ذو صلة
- حالة الخدمة: قراءة البيانات نفسها في المتصفح
- سجل التغييرات: تصفح الإدخالات مع عوامل التصفية وتقسيم الصفحات
- خارطة الطريق: التصويت على العناصر في واجهة المستخدم
- المشكلات المعروفة: قراءة المشكلات المفتوحة والتي تم حلها
- بوابة التحديثات: نظرة عامة على القسم