Endpoint چیست؟ نقطه اتصال به وب سرویس به زبان ساده

Endpoint یا نقطه پایانی در API، آدرسی است که برنامه شما برای دسترسی به یک منبع یا قابلیت مشخص به آن درخواست می فرستد.

برای مثال، برنامه می تواند از یک آدرس برای ارسال پیامک و از آدرس دیگری برای دریافت گزارش تحویل استفاده کند. در APIهای مبتنی بر HTTP، متد درخواست هم مشخص می کند چه عملیاتی روی آن مقصد انجام شود.

در این راهنما، از تعریف اندپوینت شروع می کنیم و به یک نمونه درخواست پیامکی، آموزش تست و عیب یابی می رسیم. هدف این است که هنگام خواندن مستندات یک وب سرویس، بدانید هر بخش از درخواست چه کاری انجام می دهد.

Endpoint دقیقاً چیست؟

Endpoint را می توانید مانند نشانی یک باجه خدمات در نظر بگیرید: نشانی مشخص می کند کجا مراجعه کنید و نوع درخواست شما مشخص می کند چه کاری می خواهید. در API هم آدرس، مقصد درخواست است؛ اما داده های ارسالی، متد و اطلاعات دسترسی، جزئیات کار را تعیین می کنند.

برای نمونه، در یک API فرضی، درخواست GET https://api.example.com/v1/messages/123 برای دریافت اطلاعات پیامک شماره ۱۲۳ تعریف شده است. در مستندات ممکن است فقط مسیر /messages/123 را ببینید؛ برای ساخت آدرس کامل، باید آن را به Base URL اعلام شده اضافه کنید.

تفاوت Endpoint در شبکه و API چیست؟

واژه Endpoint در امنیت شبکه هم استفاده می شود و معمولاً به دستگاه هایی مانند لپ تاپ، گوشی یا سرور اشاره دارد. Endpoint Protection به حفاظت از این دستگاه ها مربوط است. موضوع این مقاله API Endpoint است؛ یعنی نقطه تماس نرم افزار با API. بنابراین بحث آنتی ویروس و مدیریت دستگاه های شبکه، موضوع جداگانه ای دارد.

آیا هر API فقط یک Endpoint دارد؟

خیر؛ تعداد Endpointها به طراحی API بستگی دارد. یک API ممکن است چند مسیر یا تعداد زیادی مسیر برای کاربران، سفارش ها و پیام ها داشته باشد. همچنین یک مسیر می تواند با متدهای متفاوت، عملیات متفاوتی ارائه دهد؛ پس هر عملیات الزاماً به یک URL مستقل نیاز ندارد.

در بعضی معماری ها، مانند GraphQL، چندین نوع درخواست معمولاً به یک مسیر مشترک فرستاده می شود. بنابراین نمی توان برای همه APIها تعداد یا شکل ثابتی از Endpoint در نظر گرفت.

تفاوت API، Endpoint، Base URL و Resource چیست؟

این اصطلاح ها به هم مرتبط اند، اما جای یکدیگر استفاده نمی شوند. مثال زیر برای یک سرویس پیامکی فرضی است:

در بسیاری از مستندات HTTP، ترکیب متد و مسیر، یک عملیات را مشخص می کند؛ مثلاً GET /messages/123. برای شناخت ارتباط این مفاهیم با وب سرویس، مقاله تفاوت وب سرویس و API را بخوانید.

اجزای یک آدرس Endpoint از نزدیک

آدرس زیر شماتیک است و برای آموزش ساختار URL استفاده می شود. در این مثال، شناسه پیامک در مسیر و زبان پاسخ در Query String آمده است:

https://api.example.com/v1/messages/123?lang=fa

Base URL فقط دامنه نیست. آدرس پایه می تواند شامل Scheme، میزبان، پورت و بخشی از مسیر مانند /api/v1 باشد. پورت، در صورت نیاز، بعد از نام میزبان می آید. ساختار دقیق آدرس پایه را از مستندات بگیرید.

تفاوت Path Parameter و Query Parameter چیست؟

پارامتر مسیر معمولاً بخشی از نشانی منبع است؛ مثلاً در /messages/{id} باید {id} را با شناسه واقعی جایگزین کنید. پارامتر Query بعد از علامت سؤال قرار می گیرد و می تواند برای فیلتر، صفحه بندی یا تنظیم خروجی استفاده شود؛ مانند /messages?status=delivered&page=2. نام و کاربرد پارامترها را طراحی همان API تعیین می کند.

پارامترهای Query با & از هم جدا می شوند. برای مقادیری مانند فاصله و متن فارسی، از قابلیت URL encoding کتابخانه یا ابزار خود استفاده کنید. بخش Fragment که با # شروع می شود، در درخواست HTTP به سرور فرستاده نمی شود و محل ارسال پارامتر API نیست.

پیشنهاد خواندنی: مقاله REST API چیست به شناخت منطق منابع و مسیرها کمک می کند.

رابطه Endpoint با متد HTTP

در یک درخواست HTTP، URL مقصد را مشخص می کند و متد، معنای عملیات را بیان می کند. مرورگر هنگام بازکردن یک آدرس معمولاً درخواست GET می فرستد؛ بنابراین بازکردن یک Endpoint مخصوص POST در نوار آدرس، معادل فراخوانی صحیح آن نیست.

برای مثال، یک API فرضی می تواند مسیر /users/123 را با GET برای خواندن اطلاعات کاربر، با PUT برای ایجاد یا جایگزینی وضعیت منبع، با PATCH برای تغییر بخشی از اطلاعات و با DELETE برای حذف منبع ارائه کند. پشتیبانی از این متدها باید در مستندات تأیید شده باشد.

POST هم معمولاً برای ثبت داده یا درخواست انجام یک پردازش استفاده می شود؛ مثلاً POST /messages برای ثبت درخواست ارسال پیامک. از نام مسیر به تنهایی نمی توان متد درست را حدس زد.

پیشنهاد خواندنی: برای جزئیات GET، POST، PUT، PATCH و DELETE، مقاله متدهای HTTP را ببینید.

Endpoint چگونه کار می کند؟ چرخه درخواست و پاسخ

فرض کنید نرم افزار فروشگاه باید وضعیت پیامک تأیید سفارش را بگیرد. چرخه ساده شده درخواست و پاسخ چنین است:

همه پاسخ ها JSON نیستند؛ بعضی APIها XML، متن یا خروجی دیگری دارند. همچنین ممکن است قبل از رسیدن درخواست به برنامه سرور، خطای DNS، اتصال یا TLS رخ دهد. در این وضعیت الزاماً پاسخ HTTP دریافت نمی کنید.

تفاوت URL، Header و Body در درخواست

همه اطلاعات درخواست داخل آدرس قرار نمی گیرند. URL مقصد و پارامترهای مسیر یا Query را مشخص می کند؛ Header اطلاعاتی مانند قالب محتوا و اعتبارنامه را منتقل می کند؛ Body هم می تواند داده اصلی عملیات، مانند شماره گیرنده و متن پیامک، باشد.

هدر Content-Type: application/json می گوید بدنه ارسالی JSON است. هدر Accept: application/json نیز قالب پاسخ مورد قبول کلاینت را بیان می کند. این دو هدر کاربرد یکسانی ندارند و فقط نوشتن Content-Type، متن نامعتبر را به JSON معتبر تبدیل نمی کند.

نمونه Endpointهای یک وب سرویس پیامکی

جدول زیر چند الگوی آموزشی برای یک وب سرویس پیامکی را نشان می دهد. این مسیرها، نام فیلدها و پاسخ های بعدی، مستندات واقعی پیام رسان نیستند و نباید مستقیماً در پروژه استفاده شوند. دامنه example.com برای مثال زدن است.

در مستندات واقعی، ممکن است نام مسیرها یا حتی متد این عملیات متفاوت باشد. قبل از کدنویسی، آدرس پایه، متد، فیلدهای الزامی، واحد اعتبار و ساختار پاسخ را بررسی کنید.

نمونه کامل درخواست ارسال پیامک و پاسخ آن

در نمونه زیر، برنامه با POST یک درخواست ارسال ثبت می کند. YOUR_TEST_TOKEN فقط جای نگهدار است. فرض کرده ایم این سرویس از Bearer Token استفاده می کند؛ سرویس واقعی ممکن است API Key را در هدر دیگری بخواهد.

POST /v1/messages HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_TEST_TOKEN
Content-Type: application/json
Accept: application/json

{
  "to": "RECIPIENT_NUMBER",
  "text": "سفارش شما ثبت شد. کد پیگیری: ۱۲۳۴"
}

سرور فرضی می تواند درخواست را برای پردازش بپذیرد و چنین پاسخی برگرداند:

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "message_id": "msg_123",
  "status": "queued"
}

پذیرفته شدن درخواست با تحویل پیامک به گوشی یکسان نیست. در این مثال، ۲۰۲ و queued یعنی درخواست برای پردازش پذیرفته شده است. برای نتیجه نهایی باید با شناسه msg_123 گزارش بگیرید یا، اگر سرویس پشتیبانی می کند، از اعلان Webhook استفاده کنید. کد و مقدار واقعی وضعیت را مستندات مشخص می کند.

احراز هویت و امنیت Endpoint

دانستن آدرس یک Endpoint حفاظت شده، مجوز استفاده از آن نیست. سرویس ممکن است API Key، توکن دسترسی یا روش دیگری بخواهد. احراز هویت مشخص می کند درخواست کننده چه کسی است؛ مجوزدهی مشخص می کند به کدام داده یا عملیات دسترسی دارد.

مثلاً ممکن است توکن معتبر باشد، اما مجوز مشاهده گزارش حساب دیگری را نداشته باشد. از طرف دیگر، بعضی Endpointهای عمومی بدون ورود قابل استفاده اند؛ پس نیاز به توکن را باید برای همان عملیات بررسی کنید.

برای کاهش احتمال افشای اعتبارنامه، راهنمای OWASP درباره امنیت REST تأکید می کند:

Passwords, security tokens, and API keys should not appear in the URL

ترجمه: رمزهای عبور، توکن های امنیتی و کلیدهای API نباید در URL قرار بگیرند. آدرس ها ممکن است در لاگ ها ثبت شوند؛ اعتبارنامه را مطابق مستندات، معمولاً در هدر مناسب، بفرستید و از انتشار آن در کد، تصویر آموزشی و گزارش خطا جلوگیری کنید.

از HTTPS استفاده کنید و برای عبور از خطا، اعتبارسنجی گواهی TLS را غیرفعال نکنید. اگر طراح API هستید، کنترل مجوز برای هر منبع، اعتبارسنجی ورودی و محدودیت نرخ درخواست را هم در سمت سرور اجرا کنید.

چطور Endpoint را با Postman و cURL تست کنیم؟

برای تمرین اولیه، می توانید مطابق راهنمای رسمی Postman از سرویس Echo استفاده کنید. این تمرین پیامک ارسال نمی کند و فقط به فهم درخواست و پاسخ کمک می کند. اطلاعات شخصی و کلید واقعی خود را به سرویس عمومی Echo نفرستید.

1. در Postman یک درخواست جدید بسازید و متد را روی GET قرار دهید.
2. آدرس https://postman-echo.com/get را وارد کنید.
3. در بخش Params، کلید topic و مقدار endpoint را اضافه کنید.
4. روی Send بزنید و کد وضعیت، بدنه پاسخ و مقدار بازتاب داده شده پارامتر را بررسی کنید.

همین تمرین را در محیطی که cURL نصب است، با دستور زیر انجام دهید. گزینه -i هدرهای پاسخ را هم نمایش می دهد:

curl -i "https://postman-echo.com/get?topic=endpoint"

برای آزمودن API پیامکی واقعی، آدرس را از مستندات همان سرویس بردارید. اگر عملیات POST و JSON می خواهد، متد را POST بگذارید، در Body گزینه raw و قالب JSON را انتخاب کنید و اعتبارنامه را در محل تعیین شده وارد کنید. قبل از ارسال واقعی، هزینه و شماره گیرنده را بررسی کنید.

اگر درخواست در Postman موفق است و در برنامه خطا دارد، URL نهایی، متد، هدرها و بدنه را با هم مقایسه کنید. تفاوت در آدرس پایه، توکن، نوع داده فیلدها یا تنظیمات شبکه، سرنخ های مفیدی هستند. موفقیت در یک ابزار به تنهایی ثابت نمی کند تنظیمات برنامه هم یکسان است.

تفاوت Endpoint محیط تست و محیط عملیاتی

بعضی ارائه دهندگان، محیط Sandbox یا اعتبارنامه مخصوص تست دارند؛ بعضی دیگر چنین محیطی ارائه نمی کنند. رفتار تست هم یکسان نیست: ممکن است پاسخ شبیه سازی شود، ارسال فقط به شماره های مجاز انجام شود یا محدودیت دیگری وجود داشته باشد. رایگان بودن و نبود ارسال واقعی را بدون بررسی مستندات فرض نکنید.

برای نمونه، سرویس فرضی ممکن است از https://sandbox.example.com/v1 برای تست و https://api.example.com/v1 برای محیط عملیاتی استفاده کند. در سرویس دیگر، آدرس ثابت است و نوع کلید، محیط را مشخص می کند. داده، شناسه ها، مجوزها و محدودیت نرخ هم ممکن است بین دو محیط فرق کنند.

آیا از کدهای Sandbox می توان در محیط واقعی استفاده کرد؟

معمولاً می توان منطق اتصال را دوباره استفاده کرد، به شرطی که قرارداد API در دو محیط سازگار باشد. چیزی که باید بررسی یا تعویض شود، تنظیمات محیط از جمله Base URL، اعتبارنامه، شناسه های معتبر و محدودیت هاست. بنابراین متفاوت بودن آدرس ها به معنی نیاز به نوشتن دوباره تمام کد نیست.

پیش از انتقال، هماهنگی آدرس و کلید را بررسی کنید، داده آزمایشی را کنار بگذارید و یک آزمون کنترل شده با گیرنده مجاز انجام دهید. موفقیت در Sandbox تضمین کننده نتیجه تحویل یا ظرفیت یکسان در محیط عملیاتی نیست.

اشتباهات رایجی که باعث خطا می شوند

ابتدا مشخص کنید پاسخ HTTP دریافت کرده اید یا اتصال پیش از آن شکست خورده است. سپس آدرس، متد، اطلاعات دسترسی و داده ورودی را بررسی کنید. چند اشتباه متداول عبارت اند از:

کدهای وضعیت HTTP چه سرنخی می دهند؟

جدول زیر نقطه شروع عیب یابی است؛ معنای دقیق خطای تجاری را از بدنه پاسخ و مستندات بخوانید. بعضی سرویس ها برای پنهان کردن وجود یک منبع، پاسخ متفاوتی می دهند.

برای جزئیات بیشتر، راهنمای خطای وب سرویس را بخوانید. هنگام پیگیری، زمان درخواست، شناسه پیگیری و متن خطا را ثبت کنید؛ توکن و اطلاعات شخصی را از گزارش حذف کنید.

اگر خطا Timeout یا CORS بود چه کنیم؟

Timeout یعنی در مهلت تعیین شده نتیجه را دریافت نکرده اید؛ الزاماً به معنی اجرا نشدن عملیات نیست. در ارسال پیامک، تکرار بی بررسی درخواست می تواند ارسال تکراری بسازد. ابتدا گزارش یا سازوکار جلوگیری از تکرار درخواست را، اگر سرویس ارائه می دهد، بررسی کنید.

اگر درخواست از مرورگر به علت CORS مسدود می شود، مجوز دسترسی بین مبدأها در تنظیمات سرور را بررسی کنید. موفقیت همان درخواست در Postman این محدودیت مرورگر را رد نمی کند. برای API دارای کلید محرمانه، ارتباط را از بک اند خود انجام دهید؛ کلید را برای حل مشکل در JavaScript عمومی قرار ندهید.

چرا نباید Endpoint را هاردکد کنیم؟

بهتر است بخش وابسته به محیط، به ویژه Base URL، در تنظیمات متمرکز باشد تا برای جابه جایی محیط ها مجبور به تغییر چندین فایل نشوید. مسیر ثابت یک قابلیت می تواند در کد کلاینت یا SDK تعریف شود؛ مشکل اصلی، پراکندگی آدرس های محیطی و اعتبارنامه ها در کد است.

برای یک برنامه سمت سرور، تنظیمات فرضی می تواند چنین باشد:

SMS_API_BASE_URL=https://sandbox.example.com/v1
SMS_API_TOKEN=YOUR_TEST_TOKEN

آدرس سرویس معمولاً محرمانه نیست، اما کلید دسترسی محرمانه است. کلید را در سازوکار امن مدیریت اسرار یا تنظیمات محافظت شده سمت سرور نگه دارید. صرف ذخیره در فایل .env امنیت ایجاد نمی کند؛ فایل نباید وارد مخزن عمومی شود و دسترسی به آن باید محدود باشد.

متغیری که هنگام ساخت فرانت اند داخل خروجی JavaScript قرار می گیرد، برای کاربر قابل مشاهده است؛ حتی اگر نام آن در فایل محیطی نوشته شده باشد. کلید محرمانه سرویس را در بک اند نگه دارید و برای مرورگر فقط دسترسی کنترل شده برنامه خودتان را فراهم کنید.

آیا Endpoint در همه APIها یک شکل است؟

خیر. در REST، مسیرها معمولاً حول منابعی مانند کاربران و پیام ها طراحی می شوند و متد HTTP نوع عملیات را مشخص می کند. در GraphQL معمولاً درخواست ها به یک مسیر مانند /graphql می روند و Query یا Mutation، داده و عملیات را مشخص می کند؛ این الگو در مستندات رسمی GraphQL توضیح داده شده است.

در RPC تمرکز روی فراخوانی یک رویه یا تابع راه دور است؛ آدرس دهی و قالب پیام به فناوری مورد استفاده بستگی دارد. پس الگوی چند مسیر REST را به همه APIها تعمیم ندهید. تمرکز مثال های این مقاله بر APIهای HTTP است.

چطور به فهرست کامل Endpointها دسترسی پیدا کنیم؟

مرجع اصلی، مستندات رسمی همان ارائه دهنده است. در سایت یا پنل سرویس به بخش های API Reference، Developers یا مستندات وب سرویس مراجعه کنید. بعضی سرویس ها رابط تعاملی Swagger UI مبتنی بر OpenAPI یا مجموعه درخواست های Postman ارائه می کنند؛ همه APIها این ابزارها را ندارند.

1. Base URL مربوط به محیط و نسخه خود را پیدا کنید.
2. مسیر و متد عملیات مورد نیاز را بردارید.
3. پارامترهای مسیر، Query، هدرها و بدنه را همراه با نوع داده و الزامی بودن آن ها بررسی کنید.
4. روش احراز هویت، مجوزها، محدودیت نرخ و هزینه احتمالی را بخوانید.
5. نمونه پاسخ موفق و خطا را بررسی کنید؛ برای عملیات غیرهم زمان، روش پیگیری نتیجه را هم پیدا کنید.

اگر خودتان API طراحی می کنید، مسیرها را یکدست نام گذاری کنید، ورودی ها و مجوزها را در سرور بررسی کنید و نمونه درخواست، پاسخ و خطا را مستند کنید. تغییر نسخه، آزمون و پایش زمان پاسخ را هم در برنامه نگهداری API قرار دهید.

جمع بندی

Endpoint آدرس تماس برنامه با یک قابلیت یا منبع API است. برای استفاده درست از آن، علاوه بر URL، باید متد، اطلاعات دسترسی و داده مورد نیاز درخواست را بشناسید و پاسخ را مطابق مستندات تفسیر کنید. در سرویس پیامکی هم پذیرش درخواست ارسال، جای بررسی گزارش تحویل را نمی گیرد.

برای شروع اتصال به پیام رسان، به صفحه وب سرویس پیامکی مراجعه کنید و مسیر دسترسی به مستندات و امکانات حساب خود را بررسی کنید. سپس یک درخواست کنترل شده با تنظیمات و گیرنده معتبر بسازید؛ مسیرهای شماتیک این مقاله جای آدرس های واقعی سرویس را نمی گیرند.

سوالات متداول