مستندات لازم برای توسعه دهندگان

مستندات لازم در مورد چگونگی استفاده از سیستم API کوتاه کننده لینک پی‌لینک برای توسعه برنامه‌های شما. API جدید Plink URL Shortener بر روی معماری RESTful ساخته شده است و به شما اجازه می‌دهد تا با استفاده از نکات زیر، با وب‌سایت، افزونه و برنامه‌های خود ارتباط برقرار کنید. به منظور تسهیل درخواست از توسعه دهندگان، تغییراتی در API بوجود آمده است.

احراز هویت

کلید API برای درخواست‌هایی که توسط سیستم پردازش می‌شود مورد نیاز است. هنگامی که یک کاربر ثبت نام می‌کند، یک کلید API به طور خودکار برای این کاربر ایجاد می‌شود و می‌توان آن را در صفحه /user/tools یافت. کلید API باید با هر درخواست از طریق پارامتر key ارسال شود.

 GET https://plink.ir/api?key=YOURAPIKEY

بررسی پاسخ

تمام پاسخ API در قالب JSON به طور پیش‌فرض بازگشته است. برای تبدیل این به داده‌های قابل استفاده، عملکرد مناسب باید با توجه به زبان مورد استفاده قرار گیرد. در PHP، تابع json_decode() می‌تواند برای تبدیل داده‌ها به یک شی (به طور پیش‌فرض) یا یک آرایه (مجموعه دوم پارامتر به true) مورد استفاده قرار گیرد. بسیار مهم است که کلید error را بررسی کنید زیرا اطلاعاتی در مورد اینکه آیا یک خطا وجود دارد یا خیر را ارائه می‌دهد.

 $responseDecoded = json_decode($response);
// Output data
var_dump($responseDecoded);  
                
stdClass Object
(
    [error] => 0
    [short] => "https://plink.ir/DkZOb"
)  
 $responseDecoded = json_decode($response, true);
// Output data
var_dump($responseDecoded);  
                
 array (
  'error' => 0,
  'short' => 'https://plink.ir/DkZOb',
)  
                

کوتاه کردن لینک

برای ارسال یک درخواست، کاربر باید از فرمت زیر استفاده کند که متغیرهای key و url مورد نیاز هستند. برای درخواست نام مستعار سفارشی، به سادگی &custom= را در انتها اضافه کنید.

پارامتر توضیحات
key ( مورد نیاز ) Your API key.
url ( مورد نیاز ) Long URL to shorten.
custom ( اختیاری ) Custom alias instead of random alias.
type ( اختیاری ) Redirection type [direct, frame, splash]
password ( اختیاری ) Password protection
format ( اختیاری ) Output format. Default is json. [json, text]
 $curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => "https://plink.ir/api?key=YOURAPIKEY&url=https://TheLongURL.com"
]);
// $response is the result. We can use it later.
$response = curl_exec($curl);
curl_close($curl);
                

پاسخ سرور

پاسخ در قالب JSON (به طور پیش‌فرض) رمزگذاری می‌شود. این کار برای تسهیل استفاده از زبان‌های مختلف انجام می‌شود. اولین عنصر از پاسخ همیشه اگر خطایی رخ داده است (error: 1) یا نه (error: 0) ثابت کند. عنصر دوم با توجه به عنصر اول تغییر خواهد کرد.

اگر یک خطا وجود داشته باشد، عنصر دوم “msg” نام خواهد گرفت. که شامل منبع خطا است، در غیر این صورت آن را به عنوان “short” نامیده می‌شود که حاوی URL کوتاه است. (به مثال نگاه کنید)

 // No errors
{
  "error" : 0,
  "short" : "https:\/\/plink.ir\/DkZOb"
}                
 // An error has occurred
{
  "error" : 1,
  "msg" : "Please enter a valid URL"
}                

فرمت متن

شما اکنون می‌توانید پاسخ خود را در متن ساده با اضافه کردن &format=text در پایان درخواست خود، دریافت کنید. این به جای پاسخ JSON فقط https://plink.ir/DkZOb را باز می‌کند. توجه داشته باشید که اگر یک خطا رخ دهد، هیچ چیزی تولید نخواهد شد.

 $curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => "https://plink.ir/api?key=YOURAPIKEY&url=https://TheLongURL.com&format=text"
]);
// $response is the result. We can use it later.
$response = curl_exec($curl);
curl_close($curl);
                
 https://plink.ir/DkZOb                

آمار برای یک URL کوتاه

با استفاده از نقطه پایان /details می‌توانید جزئیات بیشتری را در یک URL کوتاه همراه با پارامترهای زیر دریافت کنید. شما باید نام مستعار منحصر به‌ فرد یک URL کوتاه ارسال کنید و پاسخ در JSON باشد.

پارامتر توضیحات
key ( مورد نیاز ) Your API key.
alias ( مورد نیاز ) Short URL alias.
 GET https://plink.ir/api/details
 $curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => "https://plink.ir/api/details?key=YOURAPIKEY&alias=UNIQUEALIAS"
]);
// $response is the result. We can use it later.
$response = curl_exec($curl);
curl_close($curl);
                

پاسخ سرور

پاسخ در قالب JSON (به طور پیش‌فرض) رمزگذاری می‌شود. این کار برای تسهیل استفاده از زبان‌های مختلف انجام می‌شود. اولین عنصر از پاسخ همیشه اگر خطایی رخ داده است (error: 1) یا نه (error: 0) ثابت کند. عنصر دوم با توجه به عنصر اول تغییر خواهد کرد.

اگر یک خطا وجود داشته باشد، عنصر دوم “msg” نام خواهد گرفت. که حاوی منبع خطا است، در غیر این صورت به عنوان “details” نامیده می‌شود که حاوی جزئیات URL کوتاه است و “data” که شامل آمار است.

 {
   "error": 0,
   "details":{
      "shorturl": "https:\/\/plink.ir\/DkZOb",
      "longurl": "https:\/\/plink.ir",
      "title": "GemPixel | Creative Digital Agency",
      "description": "We are a creative digital agency providing full-featured services including branding, creation of website and app development. We are also behind Premium URL shortener.",
      "location": null,
      "device": null,
      "expiry": null,
      "date": "2019-01-27 22:49:36"
   },
   "data":{
      "clicks": 4,
      "uniqueClicks": 2,
      "topCountries": {
         "Iran": 4
      },
      "topReferrers": {
         "Direct, email and other": 2,
         "https:\/\/plink.ir": 2
      },
      "topBrowsers":{
         "Chrome": 4
      },
      "topOs":{
         "Windows 10": 4
      },
      "socialCount":{
         "facebook": 1,
         "twitter": 0,
         "google": 0
      }
   }
}                

لیست لینک‌های حساب کاربری

شما می‌توانید لیست تمام لینک‌های خود را در حساب کاربری‌تان با استفاده از نقطه پایان urls دریافت کنید. بدون نیاز به پارامترهای دیگر علاوه بر کلید API، نمی‌توانید ارسال کنید. پاسخ در JSON خواهد بود و شامل تمام لینک‌های شما در حساب کاربری‌تان خواهد شد.

پارامتر توضیحات
key ( مورد نیاز ) Your API key.
 GET https://plink.ir/api/urls
 $curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => "https://plink.ir/api/urls?key=YOURAPIKEY"
]);
// $response is the result. We can use it later.
$response = curl_exec($curl);
curl_close($curl);
                

پاسخ سرور

پاسخ در قالب JSON (به طور پیش‌فرض) رمزگذاری می‌شود. این کار برای تسهیل استفاده از زبان‌های مختلف انجام می‌شود. اولین عنصر از پاسخ همیشه اگر خطایی رخ داده است (error: 1) یا نه (error: 0) ثابت کند. عنصر دوم با توجه به عنصر اول تغییر خواهد کرد.

اگر یک خطا وجود داشته باشد، عنصر دوم “msg” نام خواهد گرفت. که حاوی منبع خطا است، در غیر این صورت “data” نامیده می‌شود که حاوی این لیست URL ها است.

 {
   "error": 0,
   "data": [
      {
         "alias": "gempixel",
         "shorturl": "https:\/\/plink.ir\/gempixel",
         "longurl": "https:\/\/premiumscript.ir",
         "clicks": "4",
         "title": "Premium Script | Quality PHP Scripts & Themes",
         "description": "Premium Script is your reference for quality PHP scripts and themes at an affordable price. We developped Premium URL Shortener and Premium Media Script.",
         "date": "2019-01-27 22:49:36"
      },
      {
         "alias": "DkZOb",
         "shorturl": "https:\/\/plink.ir\/DkZOb",
         "longurl": "https:\/\/plink.ir",
         "clicks": "2",
         "title": "GemPixel | Creative Digital Agency",
         "description": "We are a creative digital agency providing full-featured services including branding, creation of website and app development. We are also behind Premium URL shortener.",
         "date": "2019-01-27 22:48:36"
      }
   ]
}