68207
API

پنج نمونه واقعی از پیام‌های خطای API کدامند؟

توسط . ارسال شده در

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

تصور اینکه چه کارهایی را نباید در مدیریت خطای API انجام داد، آسان است.

اما چه کارهایی باید انجام دهید؟ ما طیف گسترده‌ای از APIهای عمومی را بررسی کردیم تا چند نمونه از بهترین پیام‌های خطای دنیای واقعی را انتخاب کنیم. مثال‌های زیر می‌توانند به شما ایده بدهند که پیام‌های خطای API خود را چگونه مدل‌سازی کنید.

۱. Stripe API

Stripe یکی از محبوب‌ترین APIهای پرداخت است. همین موضوع آن را گزینهٔ مناسبی برای بررسی نحوه مدیریت پیام‌های خطایش می‌کند. Stripe ناامید نمی‌کند؛ پیام‌های خطای آن مفید و دقیق‌اند.

برای مثال، اگر بدون API Key درخواستی برای مشاهدهٔ همهٔ پرداخت‌های یک حساب بفرستید، پاسخ زیر را دریافت می‌کنید:

{
"error": {
"message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer YOUR_SECRET_KEY'). See https://stripe.com/docs/api#authentication for details, or we can help at https://support.stripe.com/.",
"type": "invalid_request_error"
}
}

می‌بینید چقدر مفیدتر از یک کد سادهٔ 4xx یا 5xx است؟ Stripe نه‌تنها می‌گوید چه اشتباهی رخ داده، بلکه توضیح می‌دهد چگونه آن را رفع کنید.

۲. Merge API

Merge API ابزاری برای یکپارچه‌سازی چندین API از طریق یک منبع واحد است. بنابراین انگیزهٔ بیشتری برای ارائهٔ پیام‌های خطای باکیفیت دارد. Merge API پیام‌های خطای منابع مختلف را دریافت می‌کند و باید آن‌ها را به شکلی قابل فهم و سازگار بازگرداند.

مثلاً وقتی یک منبع وجود نداشته باشد، پیام زیر برمی‌گردد:

{
"status": ۴۰۰,
"error": "Not Found",
"message": "The requested resource was not found on this server.",
"path": "/api/users/5678",
"timestamp": "۲۰۲۴-۱۰-20T12:34:56Z"
}

وجود path به کاربر کمک می‌کند بررسی کند آیا اندپوینت را درست وارد کرده است یا نه. timestamp نیز برای دیباگ و ثبت لاگ‌ها بسیار مفید است.

۳. Instagram API

اینستاگرام بیش از ۲ میلیارد کاربر فعال ماهانه دارد. بنابراین پیام‌های خطا باید کاملاً قابل فهم باشند. وقتی کاربری برای دانلود تصویری بیش از حد بزرگ درخواست می‌دهد، پیام زیر را می‌بیند:

{
"error":
{
"message": "The image size is too large.",
"type": "OAuthException",
"code": ۳۶۰۰۰,
"error_subcode": ۲۲۰۷۰۰۴,
"is_transient": false,
"error_user_title": "Image size too large",
"error_user_msg": "The image is too large to download. It should be less than 8 MiB.",
"fbtrace_id": "A6LJylpZRKw2xKLFsAP-cJh"
}
}

درست است که این پیام مقداری طولانی است، اما همچنان خودتوصیف‌گر است. پیام، مشکل را توضیح می‌دهد و کدها اطلاعات دقیق‌تری برای دیباگ فراهم می‌کنند. برای APIهایی که کارهای بسیار متفاوتی انجام می‌دهند، داشتن subcode می‌تواند بسیار مفید باشد.

۴. Salesforce API

Salesforce محبوب‌ترین کالکشن در Postman است. با توجه به حجم بالای داده‌های حساس مالی که از طریق آن انتقال می‌یابد، پیام‌های خطای دقیق اهمیت بالایی دارند.

Salesforce دارای ۱۴ پیام خطای 4xx و سه پیام 5xx است. گاهی ساده‌اند، اما تنوع زیاد آن‌ها کمک می‌کند دقیقاً بفهمید چه مشکلی رخ داده است. برای مثال، اگر اعتبارسنجی اشتباه باشد:

{"error_description": "Client authentication failed", "error": "invalid_client"}

اگر درخواست را شرطی ارسال نکنید، ممکن است پیام ۴۲۸ دریافت کنید:

{"error_description": "The request wasn't executed because it wasn't conditional. Add one of the Conditional Request Headers, such as If-Match, to the request and resubmit it.", "error": "PRECONDITION_REQUIRED"}

۵. Reltio API

در پایان، یک API اتصال‌دهندهٔ دیگر: Reltio. این API مجموعه‌ای از ابزارها برای یکپارچه‌سازی داده در یک پلتفرم واحد است. Reltio حتی عمیق‌تر از Merge است و اجازهٔ انجام عملیات CRUD را از طریق مجموعه‌ای از APIها می‌دهد.

Integrate API آن چشمگیرتر است، زیرا برای بسیاری از ابزارها و منابع محبوب، توابع یکپارچه‌سازی اختصاصی دارد. هر کدام از این اتصال‌دهنده‌ها کدهای خطای مخصوص خود را دارند، مانند این مورد برای Salesforce:

Error 1020: Invalid request, tenant {tenantId} is forbidden for current user

با بررسی این خطا در مستندات Reltio، راه‌حل نیز ارائه شده است. درست است که این پیام کاملاً خودتوصیف‌گر نیست، اما با توجه به گستردگی ابزارهایی که پشتیبانی می‌کند، قابل‌قبول است.

جمع‌بندی

APIها محدود به ارائهٔ یک خطای ۵۰۳ ساده نیستند. با قابلیت ارائهٔ محتوایی مانند JSON یا XML، این امکان وجود دارد که اسناد دقیق‌تری دربارهٔ خطا ارائه شود. پیام‌های خطای API یکی از بهترین جلوه‌های توانایی APIها هستند، چون کاربران را از مراجعه به مستندات بی‌نیاز می‌کنند و تجربه توسعه‌دهنده را بهبود می‌دهند.

البته باید تعادل میان اطلاعات کافی و امنیت حفظ شود. ارائهٔ اطلاعات بیش از حد می‌تواند به دسترسی غیرمجاز منجر شود. بهترین پیام خطا، آن است که بدون افشای اطلاعات حساس، برای توسعه‌دهنده مفید باشد و تجربهٔ بهتری ایجاد کند.

قبلیبطور کلی API-First چیست؟
بعدیآیا SDKها هنوز در عصر هوش مصنوعی مورد استفاده و مرتبط هستند؟

دیدگاهتان را بنویسید

سبد خرید
علاقه‌مندی‌ها
مشاهدات اخیر
دسته بندی ها