LinkHarbor API ایک نظر میں

REST API کے ذریعے آپ LinkHarbor کو اپنے پروگراموں سے کنٹرول کر سکتے ہیں: صفحات اور لنکس بنائیں، ڈرافٹس میں ترمیم کر کے شائع کریں، مختصر لنکس بنائیں یا اعداد و شمار اپنی رپورٹنگ میں لائیں۔ یہ مضمون ڈویلپرز کے لیے ہے اور وہ بنیادی اصول بتاتا ہے جو ہر اینڈپوائنٹ پر لاگو ہوتے ہیں۔

#کون سا راستہ موزوں ہے؟

#بیس URL اور ورژننگ

بیس URL

https://dock.at-harbor.com – تمام پروڈکٹ اینڈپوائنٹس /v1 کے تحت ہیں، مثلاً https://dock.at-harbor.com/v1/pages۔

ورژن

فی الحال صرف ورژن v1 موجود ہے۔ ورژن نمبر پاتھ کا حصہ ہے۔

پروٹوکول

صرف HTTPS۔

OpenAPI

مشین کے پڑھنے کے قابل تفصیل (OpenAPI 3.1) https://dock.at-harbor.com/openapi.yaml پر ہے۔ آپ اسے Postman، Insomnia یا کسی کوڈ جنریٹر میں لوڈ کر سکتے ہیں۔

#سینڈ باکس میں ٹیسٹنگ

ڈیولپمنٹ اور ٹیسٹنگ کے لیے ایک الگ سینڈ باکس موجود ہے۔ یہ اصل API کی طرح کام کرتا ہے لیکن اس سے بالکل الگ ہے: اپنے اکاؤنٹس، اپنا ڈیٹا، اور اس میں سے کچھ بھی آپ کی اصل ورک اسپیس میں نہیں پہنچتا۔

API

https://drydock.at-harbor.com، اوپر والے پاتھس کے ساتھ، مثلاً https://drydock.at-harbor.com/v1/pages۔

ڈیش بورڈ

https://sandbox-deck.linkharbor.com، مثلاً API کلیدیں بنانے کے لیے۔

صفحات

شائع شدہ صفحات https://<handle>.sandbox.linkharbor.com پر نظر آتے ہیں۔

اکاؤنٹ

آپ کا اصل LinkHarbor اکاؤنٹ وہاں کام نہیں کرتا۔ ایک الگ سینڈ باکس اکاؤنٹ بنائیں۔

سینڈ باکس ای میلز نہیں بھیجتا۔ اگر آپ API کے ذریعے رجسٹر کریں (POST /v1/auth/register) تو تصدیقی کوڈ براہ راست جواب میں، _dev_verification فیلڈ میں واپس آتا ہے۔ پاس ورڈ ری سیٹ اور ای میل تبدیلی پر بھی یہی ہوتا ہے۔ یہ فیلڈ صرف سینڈ باکس میں موجود ہے، اس لیے اپنے کوڈ میں اس پر انحصار نہ کریں۔

• پش نوٹیفکیشنز بند ہیں
• ادائیگیاں Stripe کے ٹیسٹ موڈ سے گزرتی ہیں، کوئی اصل رقم منتقل نہیں ہوتی
• ریٹ لمٹس اصل قدروں کا تقریباً ایک تہائی ہیں، اور نئے اکاؤنٹس فی گھنٹہ اور فی IP پتہ 5 تک محدود ہیں
• ہر مہینے کی 1 تاریخ کو 3:00 UTC پر سینڈ باکس مکمل طور پر صاف کر دیا جاتا ہے، اور اس کے بعد تمام اکاؤنٹس اور ڈیٹا ختم ہو جاتے ہیں
• ہر جواب میں ہیڈر X-Environment: sandbox ہوتا ہے

#تصدیق مختصراً

1. مالک یا ایڈمن کے طور پر ڈیش بورڈ میں “کال بیک اور API” کے تحت مطلوبہ اسکوپس کے ساتھ ایک API کلید بنائیں (Creator Pro سے)
2. POST /v1/token کے ذریعے کلید ID اور کلید کا سیکرٹ ایک ایکسیس ٹوکن سے بدلیں
3. ہر ریکویسٹ کے ساتھ ٹوکن کو ہیڈر Authorization: Bearer … میں بھیجیں
4. 15 منٹ بعد نیا ٹوکن حاصل کریں

تمام تفصیلات API کلیدیں اور ٹوکنز میں ہیں، اور اجازتیں اسکوپس میں۔

#ریکویسٹس اور جوابات

فارمیٹ

ریکویسٹس اور جوابات UTF-8 میں JSON ہوتے ہیں۔ فائل اپ لوڈز multipart/form-data بھی استعمال کرتے ہیں۔

Content-Type

باڈی والی ہر ریکویسٹ کے ساتھ ہیڈر Content-Type: application/json بھیجیں۔ کوئی بھی دوسری قسم 400 bad_request کے ساتھ مسترد ہو جاتی ہے – وہ بھی جو یہ ہیڈر نہ ہونے پر curl خود بخود -d کے لیے لگاتا ہے۔

نامعلوم فیلڈز

جو فیلڈز کسی اینڈپوائنٹ کو معلوم نہیں وہ 422 validation_failed کا سبب بنتی ہیں۔ جواب میں نامعلوم فیلڈز کے نام ہوتے ہیں۔

خراب JSON

400 invalid_json کا سبب بنتا ہے۔

سائز

اینڈپوائنٹ کے لحاظ سے باڈی زیادہ سے زیادہ 64 KB، 1 MB یا 2 MB، اور فائل اپ لوڈ 10 MB ہو سکتی ہے۔ اس سے بڑی ہو تو API 413 request_too_large سے جواب دیتا ہے۔ تمام حدیں ریٹ لمٹس میں درج ہیں۔

فہرستیں

items فیلڈ والے آبجیکٹ کی شکل میں آتی ہیں، مثلاً {"items":[…]}۔

بنانا

HTTP 201 اور نئی ID کے ساتھ جواب دیتا ہے، مثلاً {"id":123}۔

بغیر واپسی قدر والے ایکشنز

{"ok":true} سے جواب دیتے ہیں۔

خرابیاں

ہمیشہ ایک مقررہ فارمیٹ میں ہوتی ہیں جس میں مشین کے پڑھنے کے قابل کوڈ ہوتا ہے۔ دیکھیں خرابی کا فارمیٹ اور خرابی کوڈز۔

#پیجینیشن

پیجینیشن کا کوئی ایک طریقہ نہیں ہے۔ زیادہ تر فہرستیں چھوٹی ہوتی ہیں اور مکمل واپس آتی ہیں؛ صرف چند اینڈپوائنٹس کے پیرامیٹرز ہیں:

مختصر لنکس پر sort کے لیے created_desc، created_asc، redirects_desc اور redirects_asc ہیں؛ q سلگ، عنوان اور ہدف URL میں تلاش کرتا ہے (زیادہ سے زیادہ 100 حروف، بڑے چھوٹے حروف سے فرق نہیں پڑتا)۔ اعداد و شمار کے لیے period یہ قدریں قبول کرتا ہے: 24h، 7d، 30d، 90d، this_month، last_month، last_30d اور custom؛ یا آپ from اور to بھیجیں۔ granularity کی قدر hour یا day ہوتی ہے۔

#ریکویسٹ ID اور زبان

• ہر جواب میں ہیڈر X-Request-Id ہوتا ہے – سپورٹ سے رابطہ کرتے وقت اسے شامل کریں
• اگر آپ خود X-Request-Id ہیڈر بھیجیں تو API اسی کو استعمال کرتا ہے
• message میں خرابی کا متن ورک اسپیس کے مالک کی اکاؤنٹ زبان میں ہوتا ہے، ورنہ Accept-Language کے مطابق؛ error میں کوڈ ہمیشہ ایک جیسا رہتا ہے

#براؤزر سے کال کرنا؟

تکنیکی طور پر API براؤزر سے کالز کی اجازت دیتا ہے (CORS)۔ لیکن کلید کا سیکرٹ کبھی بھی ایسے کوڈ میں نہیں ہونا چاہیے جو وزیٹر کی طرف چلتا ہو – نہ کسی ویب سائٹ میں اور نہ کسی ایپ میں۔ API کو ہمیشہ اپنے سرور سے کال کریں۔

#پلانز

ہر پلان میں API کالز کا کوئی کوٹہ نہیں ہے۔ صرف فی منٹ ریٹ لمٹس لاگو ہوتی ہیں۔ آپ کے پلان کی مواد کی حدیں – جیسے صفحات، لنکس یا ہر صفحے پر بلاکس – API کے ذریعے بھی ویسے ہی لاگو ہوتی ہیں جیسے ڈیش بورڈ میں۔ دیکھیں پلانز کا موازنہ۔

#آپ کی پہلی کال

# Exchange the key for a token
curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'
# → {"token":"eyJ…","expires_in":900}

export LH_TOKEN="eyJ…"

# List pages (scope read:pages)
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

ایک مکمل مثال جو لنک شامل کرتی ہے، ڈیزائن بدلتی ہے اور شائع کرتی ہے، API کے ذریعے صفحہ اپ ڈیٹ کریں میں ہے۔