شرح استخدام واجهة التطبيقات البرمجية

عنوان الواجهة

---

عنوان واجهة التطبيقات البرمجية هي كالتالي:

https://cutt.us/api.php?url=[URL]&suffix=[SUFFIX]&userkey=[USERKEY]&format=[FORMAT]&callback=[CALLBACK]

شرح متغيرات ومفردات الواجهة

---

المتغير	مطلوب ؟	الوصف
[URL]	مطلوب *	الرابط الطويل المراد اختصاره. راجع إرشادات الاستخدام
[SUFFIX]	اختياري	اللاحقة المطلوبة للرابط
[USERKEY]	اختياري	الرمز السري للمستخدم
[FORMAT]	اختياري	التنسيق أو الصيغة المطلوبة للرد على الطلب، ويمكن الاختيار مابين التالي: plain , json , jsonp , xml
[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

و سبب المشكلة أو إيضاحها، بناء على الترقيم الموضح كما شرح سابقاً أعلاه.

مثال على الرد لطلب ناجح دون أخطاء:

https://cutt.us/Kp

مثال على رد لطلب يحتوي أخطاء:

Error: Sorry, the entered suffix contains invalid characters, Valid characters are: A-Z, a-z, 0-9, _ -

---

JSON

مثال على الرد لطلب ناجح دون أخطاء:

{"shorturl":"https://cutt.us/Kp"}

مثال على رد لطلب يحتوي أخطاء:

{"errorcode":"2","errormessage":"Error: Sorry, the entered suffix contains invalid characters, Valid characters are: A-Z, a-z, 0-9, _ -"}

---

JSONP

سوف يتم تضمين الحاوية (CallBack) التي تم تمرريها بشكل افتراضي مع الطلب، وهنا اخترت: callback=myfunc

مثال على الرد لطلب ناجح دون أخطاء:

( {"shorturl":"https://cutt.us/Kp"} );

مثال على الرد لطلب ناجح دون أخطاء مع تعيين callback=myfunc:

myfunc ( {"shorturl":"https://cutt.us/Kp"} );

مثال على رد لطلب يحتوي أخطاء:

( {"errorcode":"2","errormessage":"Error: Sorry, the entered suffix contains invalid characters, Valid characters are: A-Z, a-z, 0-9, _ -"} );

مثال على رد لطلب يحتوي أخطاء مع تعيين callback=myfunc:

myfunc ( {"errorcode":"2","errormessage":"Error: Sorry, the entered suffix contains invalid characters, Valid characters are: A-Z, a-z, 0-9, _ -"} );

---

XML

يتم تضمين الرد كاملاً، ضمن حاوية تحمل الاسم: output

مثال على الرد لطلب ناجح دون أخطاء:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<output>
    <shorturl>https://cutt.us/Kp</shorturl>
</output>

مثال على رد لطلب يحتوي أخطاء:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<output>
    <errorcode>1</errorcode>
    <errormessage>Error: You haven't supplied a URL..!!</errormessage>
</output>

إرشادات الاستخدام

---

* يجب أن تقوم بترميز الرابط بشكل صحيح، قبل أن تقوم بتوجيه طلبك إلى البوابة. يمكنك استخدام أي من الدوال التالية حسب لغة التطبيق الخاص بك:

* يمكن استخدام أي من أساليب الطلب: POST أو GET أو COOKIE مع البوابة، باستخدام ذات أسماء المتغيرات التي أوردت في شرح المتغيرات أعلاه.

* يستحسن استخدام أسلوب الطب: POST، وذلك لمحدودية طول المتغيرات في الأسلوب: GET.

* إن الحد الأقصى المتاح لاختصار الروابط عبر البوابة هو 100 رابط خلال 180 ثانية، وفي حال استهلك التطبيق الخاص بك لهذه الكمية سوف لن يكون بمقدوره اختصار المزيد من الروابط حتى انقضاء مهلة 180 ثانية بدأ من وقت أول رابط تم اختصاره.