HolyArrs API

ওয়েব অ্যাপ যে JSON API ব্যবহার করে, সেটিই /api/v1-এর অধীনে নিজের স্ক্রিপ্ট থেকে কল করুন।

প্রথম কল করুন

1. Settings > API > API keys (সেটিংস > API > API কী) খুলুন এবং শুধু যে স্কোপগুলো লাগবে সেগুলো দিয়ে একটি কী বানান। এখনই কপি করে নিন, কারণ এটি একবারই দেখানো হয়।
2. প্রতিটি কলে কীটি X-Api-Key হেডারে পাঠান। কখনো ঠিকানার মধ্যে বসাবেন না।
3. বেস ঠিকানা http://your-server:6262/api/v1 কল করুন। URL base /holyarrs হলে কল করুন http://your-server:6262/holyarrs/api/v1।

export HOLYARRS_KEY=...your key...
curl -H "X-Api-Key: $HOLYARRS_KEY" "http://your-server:6262/api/v1/health"

আপনি JSON ফেরত পাবেন। এরর আসে {"error": "plain words"} আকারে, সঙ্গে একটি HTTP স্ট্যাটাস। সিক্রেটগুলো ঢাকা অবস্থায় ফেরত আসে।

বিকল্প

একটি স্কোপ বেছে নিন

স্কোপ	কী অনুমতি দেয়
health_read	শুধু হেলথ ফিড, মনিটরিং টুলের জন্য
read	রিড রুটগুলো, হেলথ ফিডসহ
write	পরিবর্তন করা, তবে অ্যাডমিন রুট ও কন্ট্রোল বাদে
admin	মানুষজন, ইনভাইট, অনুরোধের সীমা, API কী, পাসওয়ার্ড ও টু-ফ্যাক্টর, সাইন ইন সেটিংস, রিস্টোর
control	পার্ট সুইচ, ধাপ, সংযুক্ত অ্যাপ, রিস্টার্ট ও বন্ধ করা
all	read, write ও admin। control নয়

মনিটরিং টুলকে health_read দিন, আর কিছু নয়।

একটি রুট খুঁজুন

Settings > API (সেটিংস > API) পেজে বেস ঠিকানা, স্কোপগুলো, উদাহরণ কল এবং প্রতিটি রুটের স্কোপ ও পারমিশন দেখা যায়। সাইন ইন করা থাকলে OpenAPI ফাইলটি /api/v1/openapi.json-এ পাবেন। API রুট পেজে প্রতিটি রুট তালিকাভুক্ত আছে।

আগের অ্যাপ হিসেবে HolyArrs-এর সঙ্গে কথা বলুন

Seerr, Overseerr, Bazarr এবং এ ধরনের অ্যাপ এই API ব্যবহার করে না। তারা HolyArrs-কে Sonarr ও Radarr ভেবে কথা বলে, নিজেদের আলাদা কী দিয়ে। দেখুন আগের অ্যাপের API।

কাজ না করলে

লক্ষণ: প্রতিটি কলে 401। কারণ: কীটি ভুল বা মুছে ফেলা হয়েছে। সমাধান: নতুন কী বানান।

লক্ষণ: একটি রুটে 403। কারণ: কীটির স্কোপ ওই রুটকে কভার করে না। সমাধান: Settings > API পেজে রুটটির স্কোপ দেখে নিন।

লক্ষণ: প্রতিটি কলে 404। কারণ: URL base বাদ পড়েছে। সমাধান: /api/v1-এর আগে এটি বসান। দেখুন URL base।

বিশেষজ্ঞদের জন্য

একটি রুট যোগ করুন

রুটগুলো থাকে প্রতিটি মডিউলের routes.go-তে। প্রতিটি রুট তার মেথড, পাথ ও পারমিশনসহ রেজিস্টার করা হয়, তাই প্রতিটি রুটে পারমিশন চেক থাকে।

openapi.json তৈরি হয় রুটগুলো থেকে। দুটো মেলে না গেলে TestOpenAPIGenerated ব্যর্থ হয়, তাই একই পরিবর্তনে এটিও আপডেট করুন। কোনো রুট যোগ, বাদ বা সরানো হলে রুট-টেবিল স্ন্যাপশট আপডেট না করলে সেই স্ন্যাপশটও ব্যর্থ হয়।

একবার রিলিজ হয়ে গেলে পাথ ও ফিল্ডের নাম একই থাকে। ফিল্ড যোগ করুন, কখনো নাম বদলাবেন না। পরিবর্তনের পর go run ./app/backend/tools/apidoc চালিয়ে API রুট আবার লিখুন।

মেটাডেটা সার্ভার কল

HolyArrs নাম, ছবি ও আইডি পায় HolyArrs মেটাডেটা সার্ভার থেকে। কোনো ইনস্টলকে অন্য সার্ভারে পাঠাতে HOLYARRS_METADATA_URL ব্যবহার করুন। সার্ভারের কোড এই রিপোতে নেই।

রেজিস্ট্রেশন। প্রথম লুকআপে একটি ইনস্টল কোনো বডি ছাড়া POST /v1/installations কল করে। উত্তর আসে 201 এবং {"schema_version":1,"token":"hai_..."}। অ্যাপ টোকেনটি এনক্রিপ্ট করে রাখে এবং প্রতিটি লুকআপে Authorization: Bearer <token> পাঠায়। এটি একবারই রেজিস্টার করে। 401 পাওয়ার পর আবার রেজিস্টার করে না, তাই বাতিল হওয়া ইনস্টল বাতিলই থাকে। প্রতিটি ঠিকানা গ্রুপের জন্য ঘণ্টাপ্রতি সীমা পেরিয়ে গেলে উত্তর আসে Retry-After সহ 429 registration_limit।

লুকআপ (সব GET)	রুট
সার্চ	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
মুভি	/v1/movies/tmdb/{id}
সিরিজ	/v1/shows/{tmdb or tvmaze}/{id}
সিজন	/v1/shows/tmdb/{id}/seasons/{n} (সিজন 0 হলো স্পেশাল)
গান	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

অজানা বা পুনরাবৃত্ত প্যারামিটার প্রত্যাখ্যান করা হয়। এক প্রোভাইডারের আইডি কখনো অন্যটির জন্য ব্যবহার করা হয় না।

একটি ভালো উত্তরে থাকে schema_version, source, source_id, fetched_at, expires_at, completeness, stale ও data। সারসংক্ষেপের HTML-কে সাধারণ টেক্সট হিসেবে ধরুন।

স্ট্যাটাস	মানে
400	খারাপ কোয়েরি, আবার চেষ্টা করবেন না
401	খারাপ বা বাতিল টোকেন, আবার চেষ্টা করবেন না
404	এমন কোনো রেকর্ড নেই
429	অনেক বেশি কল, Retry-After পর্যন্ত অপেক্ষা করুন
503	ব্যস্ত, অপেক্ষা করে একবার আবার চেষ্টা করুন

সংশ্লিষ্ট

• API রুট
• আগের অ্যাপের API
• এনভায়রনমেন্ট ভেরিয়েবল