مرجع الواجهة البرمجية
واجهة برمجية للمسح للقراءة فقط. كل ما يلي هو GET، والمفتاح يقرأ تمامًا ما يقرأه شخص مسجَّل الدخول، لا أكثر.
المصادقة
أرسل مفتاحك في إحدى الترويستين. لا شيء آخر يصادق على الطلب، والمفتاح المرسَل إلى مسار غير مدرج هنا يُرفض بدل أن يُخدَم.
X-Api-Key: wos_YOUR_KEY
أو بوصفه رمز bearer
Authorization: Bearer wos_YOUR_KEY
بداية سريعة
استبدل المفتاح بمفتاحك أنت.
curl -H "X-Api-Key: wos_YOUR_KEY" \ "https://api.wosatlas.com/v1/players/search?playerName=LordFrost"
نقاط الوصول
| الأسلوب | المسار | ما الذي يعيده | يُحسب بوصفه |
|---|---|---|---|
| GET | /v1/alliances/{aid}/members | جلب تحالف واحد وقائمة أعضائه | طلب |
| GET | /v1/alliances/leaderboard | ترتيب التحالفات حسب مجموع القوة | طلب |
| GET | /v1/alliances/recruiting | سرد التحالفات التي تقبل الطلبات | طلب |
| GET | /v1/alliances/search | البحث عن التحالفات بالرمز أو بالاسم | بحث |
| GET | /v1/players/{uid} | جلب حاكم واحد عبر المعرّف الداخلي uid | طلب |
| GET | /v1/players/search | البحث عن الحكّام بالاسم أو بمعرّف الحاكم | بحث |
الخطط والحدود
قيم تشغيل حالية لا حقوقًا مكتسبة. وقد تتغير.
كل حد يُحسب لكل حساب. المفاتيح الإضافية لا تشتري ميزانية إضافية.
نافذتا الحصة كلتاهما متحركتان لا فترتين تقويميتين: نافذة القراءة تنظر ثلاثين يومًا إلى الوراء من الآن، ونافذة البحث أربعًا وعشرين ساعة. وتُقاس الحصة والبحث لكل حساب لا لكل مفتاح — فكل مفتاح يملكه حساب يسحب من ميزانية واحدة.
ترويسات الاستجابة
الاستجابة المخدومة تحمل هذه كلها، وكذلك الرفض بسبب الحصة. أما الرفض بسبب الذروة فيحمل الترويسات الثلاث التي تبدأ بالسابقة X-RateLimit وحدها، والطلب المرفوض قبل القياس — 401 أو 403 — لا يحمل أيًّا منها.
| الترويسة | المعنى |
|---|---|
| X-Quota-Limit | مخصص القراءة للحساب ضمن النافذة المتحركة لثلاثين يومًا. |
| X-Quota-Remaining | ما تبقى من قراءات في تلك النافذة. |
| X-Quota-Reset | ثواني يونكس التي تخرج عندها أقدم قراءة من النافذة. |
| X-Search-Limit | مخصص البحث للحساب ضمن النافذة المتحركة لأربع وعشرين ساعة. |
| X-Search-Remaining | ما تبقى من عمليات بحث في تلك النافذة. |
| X-Search-Reset | ثواني يونكس التي يخرج عندها أقدم بحث من النافذة. |
| X-RateLimit-Limit | مخصص الذروة للحساب ضمن النافذة القصيرة. |
| X-RateLimit-Remaining | ما تبقى من طلبات في نافذة الذروة. |
| X-RateLimit-Reset | ثواني يونكس التي تدور عندها نافذة الذروة. |
| Retry-After | عدد الثواني التي يجب انتظارها قبل إعادة المحاولة. يُرسَل مع كل 429، ويخص النافذة التي رفضت. |
حين تُرفض
ثلاثة أمور مختلفة تجيب بالرمز 429، وهي غير قابلة للتبادل.
| رمز الخطأ | ما الذي حدث |
|---|---|
| QUOTA_EXCEEDED | استُنفدت حصة القراءة المتحركة لثلاثين يومًا الخاصة بالحساب. تقرأ `X-Quota-Remaining` صفرًا، بينما تبقى `X-Search-Remaining` صادقة. |
| SEARCH_QUOTA_EXCEEDED | استُنفدت حصة البحث المتحركة لأربع وعشرين ساعة الخاصة بالحساب. تقرأ `X-Search-Remaining` صفرًا، بينما تبقى `X-Quota-Remaining` صادقة. ولا يُحتسب عليها سوى مسارَي البحث. |
| RATE_LIMIT_EXCEEDED | نافذة الذروة القصيرة للحساب ممتلئة. تقرأ `X-RateLimit-Remaining` صفرًا. وهذا سقف على مقياس الثواني ينفرج من تلقاء نفسه، ولم تُمسّ أي من نافذتَي الحصة. |
رموز الأخطاء
| الرمز | الحالة | المعنى |
|---|---|---|
| INVALID_API_KEY | 401 | المفتاح غير معروف، أو مُلغى، أو أن الحساب المالك له قد حُذف. |
| ENDPOINT_NOT_ALLOWED | 403 | المسار ليس ضمن سطح المطوّرين. المفتاح المقدَّم على مسار خارج هذا السطح يُرفض بدل أن يُخدَم، فلا ترسل مفتاحًا إلى نقاط وصول لا تذكرها هذه الوثيقة. |
| QUOTA_EXCEEDED | 429 | استُنفدت حصة القراءة المتحركة لثلاثين يومًا الخاصة بالحساب. تقرأ `X-Quota-Remaining` صفرًا، بينما تبقى `X-Search-Remaining` صادقة. |
| SEARCH_QUOTA_EXCEEDED | 429 | استُنفدت حصة البحث المتحركة لأربع وعشرين ساعة الخاصة بالحساب. تقرأ `X-Search-Remaining` صفرًا، بينما تبقى `X-Quota-Remaining` صادقة. ولا يُحتسب عليها سوى مسارَي البحث. |
| RATE_LIMIT_EXCEEDED | 429 | نافذة الذروة القصيرة للحساب ممتلئة. تقرأ `X-RateLimit-Remaining` صفرًا. وهذا سقف على مقياس الثواني ينفرج من تلقاء نفسه، ولم تُمسّ أي من نافذتَي الحصة. |
مواصفة مقروءة آليًا
وثيقة OpenAPI أدناه مولَّدة من الخادم العامل، وهي نفسها التي تعرضها هذه الصفحة.