إدارة الإصدارات

يستخدم AstroWay API إدارة الإصدارات عبر URL: الإصدار مكتوب في مسار الطلب. هذا أبسط من الاعتماد على الترويسات، ويُخزَّن مؤقتًا بشكل جيد في الوكلاء (proxies).

https://api.astroway.info/v1/chart

SemVer في الـ API

نلتزم بدلالات semver.org:

• MAJOR (v1 → v2): تغييرات كاسرة للتوافق. يستمر الإصدار القديم في العمل 12 شهرًا على الأقل بعد إطلاق الإصدار الجديد.
• MINOR: نقاط نهاية جديدة وحقول اختيارية جديدة. متوافق دائمًا.
• PATCH: إصلاحات أخطاء وتحسينات في الدقة. يظهر عبر الترويسة X-Api-Version: 1.12.3 في الاستجابة.

ما لا يُعدّ breaking change

• إضافة نقطة نهاية جديدة
• إضافة حقل اختياري جديد إلى request body
• إضافة حقل جديد إلى الاستجابة
• تحسين نص رسائل الخطأ (قيم code تبقى ثابتة)
• تغييرات دقة الحسابات ضمن الحدود المعلنة ±1” (الكواكب) / ±1’ (البيوت)
• رفع rate limit أو credit budget في خطتك

هذا يعني: يجب ألا يتعطل كودك عند إضافة حقل جديد إلى الاستجابة. حلّل فقط ما تحتاجه وتجاهل الباقي.

ما هو breaking change (فقط في إصدار رئيسي)

• حذف نقطة نهاية أو إعادة تسميتها
• حذف حقل من الاستجابة أو إعادة تسميته
• تغيير نوع الحقل (مثلًا number → string)
• تغيير دلالة الحقل (ما يعنيه الاسم نفسه)
• تغيير code في استجابة الخطأ
• تشديد التحقق بما قد يكسر طلبات كانت صالحة سابقًا

Changelog

جميع التغييرات في Changelog. الإصدارات الثانوية كل 2-4 أسابيع، والتصحيحات عند جاهزيتها.

الاشتراك في التحديثات:

• RSS: https://api.astroway.info/changelog/rss.xml
• البريد الإلكتروني: Settings → Notifications → Product updates في لوحة التحكم

سياسة الإيقاف (Deprecation policy)

عندما يصبح حقل أو نقطة نهاية deprecated:

1. نعلن ذلك في changelog مع إشعار بالبريد الإلكتروني
2. تظهر في الاستجابة الترويسة Deprecation: Sun, 01 Nov 2026 00:00:00 GMT (معيار RFC 8594)
3. يستمر الـ API المُوقَف في العمل 12 شهرًا على الأقل
4. الحذف: فقط في الإصدار الرئيسي التالي