API Contracts

خمس endpoints GET (القائمة، التفاصيل، الفئة، الموضوع، المؤلِّف) + POST واحد (الاشتراك). كلها قابلة-للـ-cache في CDN، كلها مُدركة-للمحلّية، كلها تُرجع أشكال envelope { items، meta، seo } مُتَّسقة.

1 · GET /api/editorial

• Query: category? · topic? · author? · q? · sort (latest|most-read|editor-picks|long-reads|short-reads) · page · pageSize · lang.
• الاستجابة: { featured: ArticleListItem[3]، items: ArticleListItem[]، mostRead: ArticleListItem[5]، categories: CategoryItem[]، topics: TopicItem[20]، totalCount، pagination، seo }.
• ArticleListItem: { id، slug، type، title، dek، excerpt، coverImageUrl، category{slug, name}، topics[]، author{slug, displayName, role, avatarUrl}، publishedAt، readingTimeMinutes، isFeatured، isEditorPick، isPractical، viewCount }.
• Cache: 300s public + 900s s-maxage. أبطل عند نشر/تحديث المقالة.

2 · GET /api/editorial/{slug}

• الاستجابة: { article: EditorialArticle كامل + bodyHtml، author: EditorialAuthor كامل، category: EditorialCategory كامل، topics[]، images[]، relatedArticles[<=6]، mostRead[5]، connectedSignals[<=8]، translation?: { exists: bool، slug?، lang? }، seo: { metaTitle، metaDescription، canonicalUrl، ogImage، jsonLd، hreflang[] } }.
• connectedSignals مَحدود بـ 8 جانب-الخادم. القائمة الكاملة متاحة عبر /api/editorial/{slug}/signals?offset=8.
• Cache: 600s public + 1800s s-maxage. أبطل عند تحديث المقالة أو entity مرتبط.
• الأخطاء: 404 slug مجهول؛ 410 Gone حين IsActive=false ومُتقاعد عمداً؛ 503 مع retry-hint عند فشل البنية التحتية (أبداً 500 للعميل).

3 · GET /api/editorial/categories/{slug}

• Query: topic? · sort · page · pageSize · lang.
• الاستجابة: { category: EditorialCategory كامل، featured?: ArticleListItem، items: ArticleListItem[]، relatedCategories[3]، totalCount، pagination، seo }.
• 404 حين categorySlug مجهول (لا fallback للقائمة الكاملة).

4 · GET /api/editorial/topics/{slug}

• الاستجابة: { topic: EditorialTopic كامل، items: ArticleListItem[]، mostReadInTopic[5]، connectedEcosystem: { opportunities[<=4]، files[<=4]، startups[<=4] }، pagination، seo }.
• connectedEcosystem مُتَخَصِّص-بالموضوع: يُبرز entities غير-Editorial مُعَلَّمة بنفس slug الموضوع، مَحدود بـ 4 لكل نوع.

5 · GET /api/editorial/authors/{slug}

• الاستجابة: { author: EditorialAuthor كامل، stats: { totalArticles، articlesByType: {news، analysis، ...}، joinedDate }، latestArticles: ArticleListItem[]، mostReadByAuthor[5]، topicsCovered[]، pagination، seo }.

6 · POST /api/subscriptions/editorial-digest

• الـ Body: { email، preferredLang، interestCategories[]، consentPlatform (true)، consentPartners?، source: 'listing'|'category'|'topic'|'article'، articleIdContext? }.
• الخادم: يَكتب صف EditorialSubscription + يُدرج welcome email. محدود-المعدّل 5/IP/ساعة.