এক নজরে 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 ঠিকানায় ৫টিতে সীমিত
• প্রতি মাসের ১ তারিখে ৩:০০ UTC-তে স্যান্ডবক্স পুরোপুরি মুছে ফেলা হয়, এরপর সব অ্যাকাউন্ট আর ডেটা আর থাকে না
• প্রতিটি রেসপন্সে X-Environment: sandbox হেডার থাকে

#সংক্ষেপে অথেনটিকেশন

1. মালিক বা অ্যাডমিন হিসেবে ড্যাশবোর্ডে “কলব্যাক ও API”-এর অধীনে দরকারি স্কোপসহ একটি API কী তৈরি করুন (Creator Pro থেকে)
2. POST /v1/token দিয়ে কী আইডি আর কী সিক্রেটের বদলে একটি অ্যাক্সেস টোকেন নিন
3. প্রতিটি রিকোয়েস্টে টোকেনটি Authorization: Bearer … হেডারে পাঠান
4. ১৫ মিনিট পর নতুন টোকেন নিন

সব বিস্তারিত আছে 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 আসে।

আকার

এন্ডপয়েন্ট অনুযায়ী একটি বডি সর্বোচ্চ ৬৪ KB, ১ MB বা ২ MB হতে পারে, আর একটি ফাইল আপলোড ১০ MB। এর চেয়ে বড় হলে API 413 request_too_large দিয়ে উত্তর দেয়। সব সীমার তালিকা আছে রেট লিমিট-এ।

তালিকা

items ফিল্ডসহ একটি অবজেক্ট হিসেবে আসে, যেমন {"items":[…]}।

তৈরি করা

HTTP 201 আর নতুন আইডি দিয়ে উত্তর দেয়, যেমন {"id":123}।

রিটার্ন মান ছাড়া অ্যাকশন

{"ok":true} দিয়ে উত্তর দেয়।

ত্রুটি

সবসময় মেশিনে পড়ার উপযোগী কোডসহ একটি নির্দিষ্ট ফরম্যাটে আসে। দেখুন ত্রুটির ফরম্যাট ও ত্রুটি কোড।

#পেজিনেশন

সবার জন্য একটি পেজিনেশন পদ্ধতি নেই। বেশিরভাগ তালিকা ছোট এবং পুরোটা একবারে ফিরে আসে; শুধু কয়েকটি এন্ডপয়েন্টে প্যারামিটার আছে:

শর্ট লিংকের sort-এর জন্য আছে created_desc, created_asc, redirects_desc আর redirects_asc; q স্লাগ, শিরোনাম আর টার্গেট URL-এ খোঁজে (সর্বোচ্চ ১০০ অক্ষর, বড় ও ছোট হাতের অক্ষরে পার্থক্য করে না)। পরিসংখ্যানের জন্য period নেয় 24h, 7d, 30d, 90d, this_month, last_month, last_30d আর custom; বিকল্প হিসেবে from আর to পাঠান। granularity হলো hour বা day।

#রিকোয়েস্ট আইডি আর ভাষা

• প্রতিটি রেসপন্সে X-Request-Id হেডার থাকে – সাপোর্টে যোগাযোগ করলে এটি জানান
• আপনি নিজে X-Request-Id হেডার পাঠালে API সেটিই ব্যবহার করে
• message-এর ত্রুটির লেখা ওয়ার্কস্পেসের মালিকের অ্যাকাউন্টের ভাষায় আসে, নইলে Accept-Language অনুসরণ করে; error-এর কোড সবসময় একই থাকে

#ব্রাউজার থেকে কল করবেন?

প্রযুক্তিগতভাবে API ব্রাউজার থেকে কল করার অনুমতি দেয় (CORS)। কিন্তু কী সিক্রেট কখনোই ভিজিটরের দিকে চলা কোডে রাখা যাবে না – না কোনো ওয়েবসাইটে, না কোনো অ্যাপে। API সবসময় নিজের সার্ভার থেকে কল করুন।

#প্ল্যান

প্ল্যান অনুযায়ী API কলের কোনো কোটা নেই। শুধু প্রতি মিনিটের রেট লিমিট প্রযোজ্য। আপনার প্ল্যানের কনটেন্ট সীমা – যেমন পেজ, লিংক বা প্রতি পেজে ব্লক – ড্যাশবোর্ডের মতোই API-তেও প্রযোজ্য। দেখুন প্ল্যানের তুলনা।

#আপনার প্রথম কল

# কী-এর বদলে টোকেন নিন
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…"

# পেজের তালিকা (স্কোপ read:pages)
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

লিংক যোগ করা, ডিজাইন বদলানো আর পাবলিশ করার একটি সম্পূর্ণ উদাহরণ আছে API দিয়ে পেজ আপডেট করা-এ।