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.
آخر تحديث: 5 نوفمبر 2026