یکی از این بهترین شیوهها، قراردادهای نامگذاری شفاف و سازگار در سراسر API است — از منابع اندپوینتها و URIها گرفته تا فیلدها و پارامترها. نامگذاری اغلب در طراحی API نادیده گرفته میشود و همین موضوع میتواند به تجربهای ضعیف برای مصرفکنندگان منجر شود.
تصور کنید سردرگمی توسعهدهندگان را وقتی با APIای مواجه میشوند که در آن هر اندپوینت و منبع از یک قرارداد نامگذاری متفاوت استفاده میکند. برخی از آنها برای واژههای مرکب از camelCase و underscore استفاده میکنند، در حالی که برخی دیگر از حروف کوچک و خط تیره (hyphen) بهره میبرند.
برخی منابع شامل اصطلاحات تخصصی یا گونههای واژگانی هستند که ممکن است بعضی کاربران با آنها آشنا نباشند. و هیچکدام از URIها شامل نسخهبندی نیستند، که این موضوع بر سازگاری با نسخههای قبلی (backward compatibility) تأثیر میگذارد.
نامگذاری ناسازگار میتواند به تجربه ضعیف توسعهدهنده منجر شود و پذیرش کلی API را کاهش دهد. در واقع، گزارش State of the API سال ۲۰۲۵ شرکت Postman بیان میکند که «برخی شیوهها APIها را هم برای انسانها و هم برای ماشینها قابلمصرفتر میکنند.»
این شیوهها شامل قراردادهای نامگذاری سازگار هستند. نامگذاری قابل پیشبینی همچنین یک راهبرد هستهای برای قابلمصرفکردن APIها توسط عاملهای هوش مصنوعی است. این به این دلیل است که عاملهای AI برای استنباط نیت و ساختار فراخوانیهای API به نشانههای معنایی و الگوهای قابلشناسایی تکیه میکنند.
با توجه به اهمیت نامگذاری سازگار، ما چهار API محبوب را برجسته کردهایم که از قراردادهای نامگذاری مؤثر استفاده میکنند. ما این APIها را بر اساس قراردادهای نامگذاری اجزایی مانند اندپوینتها، URIها، منابع و پارامترها انتخاب کردهایم. همچنین ساختار URIها را نیز بررسی کردهایم.
Amadeus Hotel List API
Amadeus Hotel List API نمونهای عالی از شیوههای خوب نامگذاری API است.
Amadeus Hotel List API یکی از بسیاری از Self-Service Travel APIهایی است که توسط Amadeus ارائه میشوند. این APIها به اپلیکیشنها دسترسی به اطلاعات و قابلیتهای ضروری سفر را میدهند.
دستهبندیها شامل پروازها، هتلها، تجربههای مقصد، بینشهای بازار، و خودروها و ترنسفرها هستند. این شرکت همچنین Enterprise APIهایی ارائه میدهد که محتوای جامع سفر و طیف گستردهای از قابلیتها را فراهم میکنند.
سه اندپوینت Hotel List API (by-city، by-geocode، by-hotels) از قراردادهای نامگذاری شفاف و قابلدرک استفاده میکنند.
نمونههای فراخوانی API (اندپوینتهای تست)
بازگرداندن فهرستی از هتلها برای یک شهر مشخص (لندن):
بازگرداندن فهرستی از هتلها برای یک شهر با استفاده از ژئوکدینگ (سیدنی):
جستجوی هتلها با استفاده از شناسه منحصربهفرد هتل Amadeus
(Acropolis Hotel Paris Boulogne):
جستجوی هتلهای Marriott در پاریس که اجازه ورود حیوانات خانگی میدهند
(EM برای Marriott):
توسعهدهندگان Amadeus از شیوههای نامگذاری سازگار برای تمام Self-Service Travel APIهای خود پیروی میکنند.
برای مثال، Hotel List API از kebab case برای نام منابع و مسیرها استفاده میکند که خواندن و درک آنها را برای مصرفکنندگان API سادهتر میسازد.
تمام اندپوینتها شامل نسخهبندی هستند، که به تیم Amadeus کمک میکند سازگاری با نسخههای قبلی را حفظ کند و از تغییرات ناسازگار که بر کاربران تأثیر میگذارند جلوگیری نماید.
فیلدهای داده و پارامترهای کوئری از camelCase یا نسخهای با حروف بزرگ از snake case استفاده میکنند. kebab case معمولاً برای این اجزا استفاده نمیشود، زیرا با اکثر زبانهای برنامهنویسی سازگار نیست.
OpenWeatherMap API
OpenWeatherMap API بهخوبی طراحی شده و قراردادهای نامگذاری مؤثری دارد.
یکی از محبوبترین APIهای هواشناسی، OpenWeatherMap API است که حجم عظیمی از اطلاعات آبوهوا را برای مکانهای سراسر جهان فراهم میکند. این API بهصورت یک سرویس «پرداخت بهازای هر فراخوانی» (One Call API 3.0) و همچنین بهصورت مجموعههای حرفهای ارائه میشود.
این مجموعهها شامل دادههای آبوهوای فعلی و پیشبینیهای ساعتی، دادههای تاریخی آبوهوا، و نقشههای هواشناسی هستند. این شرکت همچنین APIهای تخصصی مانند Solar Irradiance API را ارائه میدهد که دادههای خورشیدی را بر اساس یک مکان مشخص فراهم میکند.
سازگاری در نامگذاری را میتوان در فراخوانیهای مختلف API مشاهده کرد.
نمونههای فراخوانی API
دریافت دادههای آبوهوای فعلی برای یک مکان مشخص (توکیو، ژاپن):
دریافت دادههای پیشبینی ساعتی برای یک مکان مشخص (پاریس، فرانسه):
دریافت دادههای فعلی آلودگی هوا برای یک مکان مشخص (لسآنجلس، کالیفرنیا):
دریافت دادههای تاریخی ساعتی آبوهوا برای یک مکان مشخص (رم، ایتالیا):
توسعهدهندگان OpenWeatherMap از نامهای ساده و شهودی در سراسر API استفاده کردهاند. این API شامل اصطلاحات تخصصی هواشناسی که برخی مصرفکنندگان ممکن است با آنها آشنا نباشند نمیشود.
وقتی نامهایی مانند «forecast» و «hourly» را در URI میبینید، میدانید که یک پیشبینی ساعتی آبوهوا برای مکان مشخص دریافت خواهید کرد.
آنها نسخهبندی را در URI گنجاندهاند، که به توسعهدهندگان کمک میکند فوراً ببینند کدام نسخه از API فراخوانی میشود و تغییرات را پیگیری کنند. اسلشهای رو به جلو سلسلهمراتب مجموعهها و منابع منفرد را نشان میدهند، که API را شهودیتر میکند.
نحوه نامگذاری و ساختاردهی منابع و URIها درک عملکرد هر فراخوانی API را برای مصرفکنندگان آسانتر میسازد.
Spotify Web API
Spotify API بهخوبی ساختاربندی شده و نامگذاری اندیشیدهشدهای دارد که به مصرفکنندگان اجازه میدهد بهراحتی بفهمند هر اندپوینت چه کاری انجام میدهد.
Spotify بهعنوان محبوبترین سرویس اشتراکی استریم صوت و موسیقی جهان شناخته میشود، بنابراین منطقی است که بسیاری از توسعهدهندگان بخواهند Spotify Web API را با اپلیکیشنهای خود یکپارچه کنند.
این API به توسعهدهندگان اجازه میدهد اپلیکیشنهایی بسازند که با سرویس Spotify تعامل داشته باشند و اقداماتی مانند مدیریت پلیلیستها و کنترل پخش را انجام دهند.
نمونههای فراخوانی API
دریافت اطلاعات یک آلبوم منفرد از کاتالوگ Spotify برای بازار کانادا:
دریافت هنرمندان برتر کاربر فعلی بر اساس رفتار کاربری اندازهگیریشده (affinity محاسبهشده):
دریافت وضعیت فعلی پخش برای کاربر:
دریافت قطعههای برتر یک هنرمند بر اساس کشور (بازار کانادا):
Spotify Web API دارای اندپوینتها و منابع متعددی است که همگی از شیوههای نامگذاری شفاف و سازگار پیروی میکنند. تیم توسعه از نامگذاری ساده برای منابع تکنمونهای (singleton) و از اسمهای جمع برای مجموعهها استفاده میکند که آنها را شهودیتر میسازد.
این تیم از گنجاندن کاراکترهای ویژه در URIها اجتناب کرده است؛ برای مثال،
top-tracks در مقابل top%20tracks.
افزودن کاراکترهای ویژه بهعنوان یک شیوه بد در نظر گرفته میشود، زیرا برخی مصرفکنندگان ممکن است به آنها دسترسی نداشته باشند و این موضوع باعث سردرگمی شود. همچنین URIها را با اضافه نکردن اسلش انتهایی تمیز نگه داشتهاند — این کار ضروری نیست و بهعنوان یک شیوه ضعیف در نظر گرفته میشود.
Stripe API
نامگذاری مؤثر مسیر زیادی را طی میکند، بهویژه وقتی API به بزرگی Stripe باشد.
API شرکت Stripe قابلیتهای متعددی را ارائه میدهد — از پرداختهای جهانی و خودکارسازی درآمد گرفته تا مدیریت پول و تأیید هویت. این API دارای گروههای متعددی از منابع (مجموعهها) است که میتوانید در آنها جستجو کرده و فهرست بگیرید.
برخی درخواستها شامل ارجاع به کوئریهای قبلی ایجادشده با Stripe’s Search Query Language هستند.
نمونههای فراخوانی API
جستجو برای فاکتورها:
دریافت فهرستی از فاکتورها بر اساس وضعیت:
بازگرداندن فهرستی از فایلهای قابلدسترس توسط حساب شما و بر اساس هدف:
دریافت فهرستی از تمام نشستهای پرداخت (checkout sessions):
توسعهدهندگان به دلایل زیادی Stripe API را دوست دارند. این API با مستندات عالی و SDKهایی در زبانهای برنامهنویسی مختلف ارائه میشود.
مانند سایر APIهای ذکرشده در بالا، Stripe API از نامگذاری مؤثر استفاده میکند — اسمهای جمع برای مجموعهها، نامهای قابلدرک برای منابع، نسخهبندی، اسلشهای رو به جلو برای نمایش سلسلهمراتب، و موارد دیگر.
Stripe یک API بسیار بزرگ ارائه میدهد که بر اساس دستههای منابع سازماندهی شده است. با این حال، تیم توسعه شرکت یک راهبرد نامگذاری را پیادهسازی کرده است که به مصرفکنندگان کمک میکند بفهمند هر اندپوینت و منبع چه کاری انجام میدهد.
بهبود تجربه توسعهدهنده با قراردادهای نامگذاری عالی
ارائهدهندگان API باید برای هر API راهنماهای سبک (style guides) تعریف کنند و این راهنماها باید شامل قراردادهای نامگذاری سازگار باشند. بدون مقداری راهنمایی، هر توسعهدهندهای که در طراحی API دخیل است بهصورت مستقل تصمیم میگیرد از چه قرارداد نامگذاریای استفاده کند.
این موضوع به اندپوینتها، منابع و URIهای آشفته و گیجکننده منجر خواهد شد. اما وقتی توسعهدهندگان همگی در یک مسیر باشند، به نامگذاری سازگاری دست مییابید که به ایجاد تجربهای بهتر برای مصرفکنندگان انسانی و عاملهای هوش مصنوعی بهطور یکسان کمک میکند.
