سالار کابلی

سرویس کوتاه کننده آدرس ققنوس، سال گذشته معرفی شد و ما تا امروز شاهد بازخوردهای خوبی بودیم. تمرکز اصلی ما برای این روی محصول، سادگی استفاده، دسترسی آسان و امنیت بالا است. به طور خلاصه امکانات کوتاه کننده آدرس ققنوس به شرح زیر است:

• امکان انتخاب نوع آدرس: عددی، عدد و حروف، متن دلخواه
• دسترسی از طریق تلفن همراه، وب و افزونه‌ی مرورگر کروم (و به زودی سافاری)
• پشتیبانی از سه زبان فارسی، انگلیسی و اسپانیایی
• امکان دسترسی از طریق API برای توسعه‌دهندگان یا برنامه‌های دیگر
• عدم ذخیره اطلاعات شخصی کاربر مانند آدرس IP

راهنمای استفاده از api

http://p5x.co/api/shorten/

ورودی

• پارامتر url: این پارامتر ضروری است.
  مقدار این پارامتر بایستی یک آدرس صحیح وب باشد. در صورتی که آدرس صحیح نباشد، سیستم یک پیام خطا تولید خواهد کرد.
   ‌
• پارامتر type: این پارامتر اختیاری است.
  مقدار این پارامتر می‌توانید یکی از سه مقدار: id، alpha یا custom باشد. این پارامتر نوع تولید آدرس را مشخص می‌کند. مقدار پیش‌فرض id است. نوع id، یک شناسه عددی به طور خودکار تولید خواهد کرد. مانند: ۱۲۳۴، نوع alpha، یک شناسه ۶کاراکتری تصادفی از ترکیب حروف و اعداد تولید می‌کند (بهتر برای امنیت) مانند: an4s82 ، و نوع custom متن دلخواه شما را در انتهای آدرس قرار می‌دهد (توضیح بیشتر در پارامتر بعدی).
   ‌
• پارامتر custom_data:
  در صورتی که مقدار پارامتر قبلی یعنی type را custom انتخاب نمایید، ارسال پارامتر custom_data ضروری است. مقدار این پارامتر باید یک رشته ترکیبی از حروف و اعداد باشد با طول بین ۳ تا ۱۰ کاراکتر. فقط کاراکترهای لاتین قابل قبول اند، مانند: wud1390. در صورتی که مقدار انتخاب شده تکراری باشد یا صحیح نباشد، سیستم یک پیام خطا تولید خواهد کرد.
   ‌
• پارامتر locale: این پارامتر اختیاری است.
  ارسال این پارامتر زبان پیام‌های خطای تولید شده را تعیین می‌کند. مقدار این پارامتر به صورت پیشفرض en (زبان انگلیسی است). شما می‌توانید یکی از مقادیر fa (برای فارسی)، en (برای انگلیسی) یا es (برای اسپانیایی) را به عنوان مقدار این پارامتر ارسال کنید. توجه کنید که تعیین زبان فقط برای تغییر زبان پیام‌های خطا کاربرد دارد و در تولید آدرس کوتاه تاثیری نخواهد داشت.
   ‌
• پارامتر output: این پارامتر اختیاری است.
  این پارامتر نوع خروجی را تعیین می‌کند و مقدار آن به صورت پیش‌فرض json می‌باشد. در حال حاضر، تنها گزینه ممکن برای شما raw است. در صورتی که مقدار raw را به این پارامتر ارسال کنید، سیستم آدرس کوتاه شده (یا پیام‌های خطا) را به صورت خام در خروجی نمایش خواهد داد. این گزینه برای سیستم‌هایی که توان پردازش JSON را نداند و از API تنها انتظار آدرس کوتاه شده را دارند کاربرد دارد.
   ‌
• پارامتر callback: این پارامتر اختیاری است.
  شما می‌توانید یک رشته را به عنوان مقدار این پارامتر ارسال کنید تا نتیجه عملیات API به عنوان اولین آرگومان تابع مورد نظر شما ارسال گردد. برای مثال اگر شما مقدار print را ارسال نمایید، خروجی API به صورت print({...}); خواهد بود، این گزینه برای استفاده از کوتاه کننده آدرس ققنوس، از طریق جاواسکریپت کاربرد دارد. برای مثال، اگر قصد دارید با استفاده از امکانات Ajax فریم‌وورک jQuery، به API متصل شوید، باید پارامتر callback=? را به همراه درخواست ارسال نمایید، تا نتیجه عملیات توسط jQuery قابل خواندن باشد.

خروجی

http://p5x.co/api/shorten/?url=http%3A%2F%2Fsallar.me%2F

{"status":"success","message":"http:\/\/p5x.co\/30","thanks":"A piece of cake :)"}

• متغیر status:
  این متغیر وضعیت خروجی را مشخص می‌کند و مقدار آن ممکن است یکی از مقادیر success یا error باشد. اولی در صورت موفقیت آمیز بودن عملیات تبدیل و دومی در صورت بروز خطا.
   ‌
• متغیر message:
  این متغیر در صورت موفقیت آمیز بودن عملیات تبدیل، حاوی آدرس کوتاه شده و در غیر اینصورت حاوی پیام خطا خواهد بود.
   ‌
• متغیر thanks:
  در صورت موفقیت آمیز بودن عملیات تبدیل، پیام تشکر سیستم در این متغیر قرار می‌گیرد. در صورت بروز خطا مقدار این متغیر null خواهد بود.

نکات مهم

• در صورتی که یک آدرس کوتاه شده توسط کوتاه کننده آدرس ققنوس را به عنوان پارامتر url ارسال نمایید، سیستم به جای کوتاه کردن مجدد ِ آدرس کوتاه شده، آدرس اصلی (و بلند) را در اختیار شما قرار خواهد داد.
• در صورتی که قصد دارید از متد GET (مانند مثال بالا) استفاده نمایید، باید حتما آدرس وب مورد نظر را به صورت انکد شد و مناسب برای Query String ارسال نمایید. برای مثال، در زبان پی‌اچ‌پی می‌توانید از تابع urlencode استفاده کنید. در صورتی که اینکار را انجام ندهید، پاسخی از سیستم دریافت نخواهید کرد. (رجوع شود به مثال بالا). ولی در صورتی که از متد POST استفاده کنید، خود مرورگر و جاواسکریپت اینکار را برای شما انجام می‌دهند.

یک مثال

var params = {
    'url'    : 'http://sallar.me/',
    'type'   : 'alpha',
    'locale' : 'fa'
};
var api = 'http://p5x.co/api/shorten/?callback=?';

$.post(api, params, function(data)
{
    if( data.status == 'success' ){
        //Success! data.message: http://p5x.co/s79bu1
    }
    else{
        //Error, Show data.message
    }
}, "json");