الدليل
عنوان الواجهة
عنوان واجهة التطبيقات البرمجية هي كالتالي:
شرح متغيرات ومفردات الواجهة
المتغير | مطلوب ؟ | الوصف |
---|---|---|
[URL] | مطلوب * | الرابط الطويل المراد اختصاره. راجع إرشادات الاستخدام |
[SUFFIX] | اختياري | اللاحقة المطلوبة للرابط |
[USERKEY] | اختياري | الرمز السري للمستخدم |
[FORMAT] | اختياري | التنسيق أو الصيغة المطلوبة للرد على الطلب، ويمكن الاختيار مابين التالي: |
[CALLBACK] | اختياري | الدالة أو الحاوية التي ترغب أن يتم تضمين الرد خلالها، وتعمل فقط مع تنسيق: jsonp |
رسائل الأخطاء
تعريب وشرح الرسائل التي يولدها النظام بناء على رقم الخطأ:
الرقم | التعريب |
---|---|
1 | لم تقم باختيار رابط لاختصاره، أو الرابط المدخل يحمل تنسيق غير صحيح. |
2 | اللاحقة المدخلة مستخدمة بالفعل، أو تحوي رموز غير مسموحة. الرموز المسموحة: A-Z a-z 0-9 - _ |
3 | عفواً، الرابط المدخل في القائمة السوداء. |
4 | الخدمة غير متاحة الآن، أو حدث خطأ ما أثناء تنفيذ الطلب. |
5 | لقد استهلكت كمية اختصار الروابط القصوى المتاحة خلال الفترة الزمنية السابقة. |
الردود والإستجابة
عند النجاح في ارسال طلب يتم الرد عليك برسالة سواء تم اختصار الرابط بنجاح أو لم يتم اختصاره مع توضيح السبب، وهنا تفسير حاوية الردود
الحاوية | الوصف |
---|---|
shorturl | يحتوي على الرابط المختصر |
errorcode | في حال حدوث خطأ سيتم الرد بهذه الحاوية مع رقم الخطأ |
errormessage | حاوية تفسير الخطأ الذي حصل |
أمثلة على الردود
PLAIN
- سوف يرد الخادم في رأسية الرد بالرمز 200 (HTTP/1.1 200 OK)، فقط في حال عدم وجود مشاكل في الطلب مالم يكن هناك مشكلة داخلية في النظام أو الخوادم.
- يتم تضمين الرد كاملاً أياً يكن، في صلب الصفحة أو الرد، سواء كان خطأ أو رابط مختصر.
- في حال نجاح الطلب، بداية الرسالة تبدأ بـ: https:// ، و في حال الفشل بـ: Error
- في حال وجود أخطاء في الطلب، سوف يرد الخادم في رأسية الرد برمز يوضح نوع الخطأ كالتالي، وسوف يحتوي صلب الصفحة على رسالة الخطأ:
[1]: HTTP/1.1 400 Bad Request
[2]: HTTP/1.1 406 Not Acceptable
[3]: HTTP/1.1 403 Forbidden
[4]: HTTP/1.1 503 Service Temporarily Unavailable
[5]: HTTP/1.1 502 Bad Gateway
و سبب المشكلة أو إيضاحها، بناء على الترقيم الموضح كما شرح سابقاً أعلاه.
مثال على الرد لطلب ناجح دون أخطاء:
مثال على رد لطلب يحتوي أخطاء:
JSON
مثال على الرد لطلب ناجح دون أخطاء:
مثال على رد لطلب يحتوي أخطاء:
JSONP
سوف يتم تضمين الحاوية (CallBack) التي تم تمرريها بشكل افتراضي مع الطلب، وهنا اخترت: callback=myfunc
مثال على الرد لطلب ناجح دون أخطاء:
مثال على الرد لطلب ناجح دون أخطاء مع تعيين callback=myfunc:
مثال على رد لطلب يحتوي أخطاء:
مثال على رد لطلب يحتوي أخطاء مع تعيين callback=myfunc:
XML
يتم تضمين الرد كاملاً، ضمن حاوية تحمل الاسم: output
مثال على الرد لطلب ناجح دون أخطاء:
مثال على رد لطلب يحتوي أخطاء:
إرشادات الاستخدام
* يجب أن تقوم بترميز الرابط بشكل صحيح، قبل أن تقوم بتوجيه طلبك إلى البوابة. يمكنك استخدام أي من الدوال التالية حسب لغة التطبيق الخاص بك:
- PHP: urlencode
- JavaScript: encodeURIComponent
- Python:urlib.quote
- Dot. Net: Url.UrlEncode
- Delphi: TIdURI.URLEncode
* يمكن استخدام أي من أساليب الطلب: POST أو GET أو COOKIE مع البوابة، باستخدام ذات أسماء المتغيرات التي أوردت في شرح المتغيرات أعلاه.
* يستحسن استخدام أسلوب الطب: POST، وذلك لمحدودية طول المتغيرات في الأسلوب: GET.
* إن الحد الأقصى المتاح لاختصار الروابط عبر البوابة هو 100 رابط خلال 180 ثانية، وفي حال استهلك التطبيق الخاص بك لهذه الكمية سوف لن يكون بمقدوره اختصار المزيد من الروابط حتى انقضاء مهلة 180 ثانية بدأ من وقت أول رابط تم اختصاره.