منصة روافد للمطورين

جميع الأمثلة التالية هي طلبات قراءة. لا ترسل بيانات حساسة في query string، ولا تضع مفاتيح الشركاء في كود عميل عام أو تطبيق متصفح يمكن فحصه.

curl -sS \
  'https://healthrenewal.org/api/v1'

curl -sS \
  'https://healthrenewal.org/api/v1/content?limit=5'

curl -sS \
  'https://healthrenewal.org/api/v1/search?q=autism&limit=5'

curl -sS \
  'https://healthrenewal.org/api/v1/evidence-discovery?q=autism&providers=europe_pmc,crossref,datacite&limit=5'

مثال JavaScript

const response = await fetch(
  'https://healthrenewal.org/api/v1/content?limit=5',
  { headers: { Accept: 'application/json' } }
);
if (!response.ok) throw new Error(`Rawafid API: ${response.status}`);
const payload = await response.json();
console.log(payload.data, payload.pagination);

المجموعات المسماة تشمل: articles، guides، research، conditions، comparisons، tools، courses، learning-paths، resources، protocols، interventions، assessments، glossary، pages، sectors، categories وtags.

القراءة العامة لا تتطلب مفتاحًا. عند وجود تكامل مؤسسي يمكن إرسال مفتاح اختياري عبر X-API-Key أو Authorization: Bearer …. المفتاح يظهر مرة واحدة عند الإصدار، ولا يخزن في قاعدة البيانات بنصه الخام؛ يخزن SHA-256 فقط.

مثال طلب شريك من الخادم

curl -sS \
  -H 'X-API-Key: rawafid_live_REDACTED' \
  'https://healthrenewal.org/api/v1/content?limit=25'

الحصة الافتراضية للشريك الجديد في البنية الحالية هي 120 طلبًا/دقيقة و25,000 طلب/يوم، لكنها قابلة للتخصيص لكل شريك. اعتبر رؤوس الاستجابة هي المصدر التشغيلي النهائي: X-RateLimit-Minute-Limit، X-RateLimit-Minute-Remaining، X-RateLimit-Day-Limit، X-RateLimit-Day-Remaining. عند التجاوز يعود 429 وRetry-After.

قاعدة أمنية: مفتاح Partner API سر مؤسسي؛ لا تضعه في JavaScript عام، تطبيق ويب مكشوف، مستودع، سجل analytics أو URL.

# First change-stream page
curl -sS 'https://healthrenewal.org/api/v1/changes?since=2026-09-01T00:00:00Z&limit=100'

# Subsequent page: keep since and pass the opaque next_cursor
curl -sS 'https://healthrenewal.org/api/v1/changes?since=2026-09-01T00:00:00Z&limit=100&cursor=NEXT_CURSOR'

GET /api/v1/content يعرض فقط المحتوى الذي حالته published وقابل للفهرسة ووقت نشره قد حل. تفاصيل المادة تضيف النص المنظم/النصي، المراجع وملف الحقوق.

GET /api/v1/sources و/sources/{id} يوفران سجلًا عامًا للمصادر المستخدمة في مواد منشورة. التفاصيل قد تشمل related_identifiers، contributors مع ORCID، انتماءات مؤسسية مع ROR، الإصدارات، مواضع الاستشهاد، rights_profiles وtranslations.

العلاقات من روافد إلى المصدر يمكن تمثيلها آليًا بعلاقة DataCite-compatible مثل IsReferencedBy نحو الصفحة القانونية المنشورة، مع عدم اختلاق ORCID/ROR عند غياب تحقق موثوق.

GET /api/v1/evidence-discovery?q=... يستخدم افتراضيًا europe_pmc,crossref,datacite. فشل مزود واحد يُعزل ويظهر في حالة المزود بدل إسقاط بقية النتائج.

النتائج المطبّعة قد تتضمن العنوان، الملخص عند توفره، السنة، المجلة/الناشر، المؤلفين، DOI وPMID وPMCID وLens/OpenAlex عند توفرها، حالة الوصول المفتوح/السحب، الاستشهادات، وprovenance. DataCite creators/contributors وnameIdentifiers وrelatedIdentifiers تُقرأ عندما يقدمها السجل. ORCID وROR لا يُنشآن تخمينيًا.

Lens هو opt-in فقط

لا يدخل Lens في المجموعة الافتراضية. لاستخدامه أرسل providers=lens أو أضفه صراحة إلى المزودات. الاعتماد LENS_SCHOLARLY_API_TOKEN يبقى server-side.

الحصة التشغيلية المطبقة على Lens هي 10 طلبات/دقيقة و20,000 طلب/شهر مع fail-closed guard مشترك بين الخوادم. كل سجل Lens يحتفظ بـLens ID ورابط السجل الأصلي، وعند عرضه يجب إظهار Data Sourced from The Lens وفق سياسة الإسناد.

التوثيق التفصيلي لتكامل Lens → · Machine-readable Lens manifest ↗

مثال ETag

ETAG=$(curl -sSI 'https://healthrenewal.org/api/v1/content?limit=5' | awk -F': ' 'tolower($1)=="etag" {print $2}' | tr -d '\r')
curl -i -H "If-None-Match: $ETAG" 'https://healthrenewal.org/api/v1/content?limit=5'

الأخطاء تعود JSON مع error.code وerror.message وerror.request_id، وقد يظهر error.parameter لخطأ معلمة محددة.

{
  "error": {
    "code": "invalid_parameter",
    "message": "...",
    "parameter": "q",
    "request_id": "..."
  },
  "meta": { "api_version": "1.2.0" }
}

الوضع المحافظ الافتراضي للمحتوى هو link_and_citation_only ما لم توجد رخصة صريحة تسمح بأكثر. وجود record في API أو availability للـmetadata لا يمنح تلقائيًا حق إعادة نشر الملخص أو النص الكامل أو الصور أو مجموعة بيانات المزود.

rights_profiles تفصل بين إتاحة metadata وحق إعادة استخدامها وبين إتاحة المحتوى وحق إعادة استخدامه. القيمة unknown تعني أن الإذن غير مثبت، لا أنها موافقة.

translations يمكن أن يسجل الحقل المترجم، لغة المصدر والهدف، طريقة الترجمة، الأداة/الإصدار عند الاستخدام الآلي، هوية المترجم والمراجع وORCID/ROR عند توفر تحقق، وحالة المراجعة. الترجمة المحلية لا تُعرض كأنها metadata أصلية بلا provenance.

الخلاصات تدعم validators وطلبات 304. إذا تعذر الوصول إلى كتالوج المحتوى الأساسي فإنها تعيد 503 مع Retry-After بدل نشر خلاصة فارغة تبدو سليمة.

هل أحتاج مفتاح API للبدء؟

لا. ابدأ بالواجهة العامة. المفتاح المؤسسي اختياري ويستخدم عندما نحتاج تعريف الشريك، scopes وحصصًا مضبوطة.

هل يمكنني سحب المكتبة كلها عبر البحث؟

لا يُنصح بتحويل endpoint البحث إلى bulk crawler. استخدم pagination للمحتوى، change stream للمزامنة التفاضلية، والخلاصات أو واجهات الحصاد المناسبة للمهمة.

هل next_since كافٍ للمزامنة متعددة الصفحات؟

استخدم next_cursor طالما has_more=true. next_since موجود للتوافق كـtimestamp checkpoint ولا يحل محل المؤشر المركب عند وجود صفحات لاحقة.

هل API تعني أن كل البيانات قابلة لإعادة التوزيع؟

لا. افحص ملف الحقوق ورخصة المصدر وشروط المزود. الإتاحة التقنية ليست ترخيصًا.

أين أجد العقد الآلي؟

https://healthrenewal.org/api/openapi.json. ويمكن بدء الاكتشاف من https://healthrenewal.org/api/v1.

لطلب Partner API، نطاقات مختلفة، مراجعة interoperability أو الإبلاغ عن مشكلة مع X-Request-Id، تواصل عبر contact@healthrenewal.org.

عند الإبلاغ عن مشكلة: أرسل المسار، وقت الطلب، حالة HTTP، وX-Request-Id. لا ترسل مفتاح API كاملًا بالبريد.