# نتیجه‌ای نیست یا خطای API: چگونه تفاوت را بفهمیم؟

> نتایج خالی، پاسخ جزئی و خطای API ROOTE را تشخیص دهید. مختصات، فیلترها، پوشش و محدودیت‌ها را بررسی کنید تا پیام مناسب نمایش داده شود.

Source: https://www.roote.ai/fa/guides/no-result-or-api-error-how-to-differentiate/
Language: fa
Author: ROOTE

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

برای ROOTE ابتدا پاسخ HTTP، سپس وضعیت کسب‌وکار، کالکشن مورد انتظار و پوشش را بررسی کنید. این کار از نمایش «هیچ توالت» هنگام شکست تماس با سرویس‌ها یا «هیچ ایستگاهی» پس از پایان زمان انتظار جلوگیری می‌کند.

## خواندن سه لایه پاسخ

| لایه | موارد قابل بررسی | نتیجه قابل استنتاج |
| --- | --- | --- |
| انتقال | اتصال، زمان انتظار و وضعیت HTTP | آیا درخواست موفق بوده؟ |
| قرارداد | JSON معتبر، نسخه و فیلدهای مورد انتظار | آیا پاسخ قابل استفاده است؟ |
| نتیجه کسب‌وکار | وضعیت، مجموعه‌ها، پوشش، هشدارها و متا | در محدوده درخواست شده چه می‌دانیم؟ |

کد HTTP ۲۰۰ به تنهایی برای اعتبارسنجی جستجو کافی نیست. پاسخ ممکن است اجرای جزئی یا وضعیت خطا را نشان دهد. برعکس، ۴۰۴ در یک مسیر روش معمول برای نمایش کالکشن خالی نیست: URL و قرارداد را بررسی کنید.

## درک وضعیت‌های success، empty، partial و error

| وضعیت | عمل توصیه شده |
| --- | --- |
| موفقیت | پس از اعتبارسنجی موجودیت‌ها را نمایش دهید و محدودیت‌ها را حفظ کنید |
| خالی | اعلام کنید که برای این جستجو هیچ نتیجه‌ای بازنگشته |
| جزئی | اطلاعات قابل استفاده را همراه با هشدارهای مربوطه نمایش دهید |
| خطا | جستجو را به عنوان ناموجود نمایش دهید؛ نتیجه‌گیری درباره نبود مکان‌ها نکنید |

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

## درخت تصمیم‌گیری برای رابط شما

```
1. La requête a-t-elle abouti ?
   Non → indisponibilité réseau ou délai dépassé.
2. Le statut HTTP est-il acceptable selon le contrat ?
   Non → traiter le code et le message d'erreur.
3. Le JSON respecte-t-il le schéma attendu ?
   Non → réponse inexploitable, jamais "aucun résultat".
4. Le statut métier est-il error ?
   Oui → recherche indisponible.
5. Le statut est-il partial ou la couverture limitée ?
   Oui → résultats utilisables + avertissement.
6. La collection attendue est-elle vide ?
   Oui → aucun résultat retourné dans ce périmètre.
   Non → afficher les résultats et leurs limites.
```

## بررسی پارامترها به ترتیب درست

ابتدا عرض و طول جغرافیایی، ترتیب آنها و شهری که دریافت شده را بررسی کنید. سپس واحد شعاع و واژگان فیلترها را کنترل کنید. API سرویس‌ها از types=toilets استفاده می‌کند؛ URL نقشه از modes=toilets. این پارامترها به قراردادهای متفاوتی تعلق دارند.

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

[ساخت جستجوی API حول مختصات GPS](https://www.roote.ai/fa/guides/chegooneh-dar-jeostojoyi-estgahaye-naghdar-ba-api/)

## برخورد با منبع ناموجود بدون از دست دادن دیگر منابع

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

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

## سازگار کردن پیام‌ها و واکنش‌ها

| وضعیت | پیامی که باید در رابط شما تنظیم شود | اقدام |
| --- | --- | --- |
| خالی | هیچ نتیجه‌ای با این فیلترها در این منطقه برگشت نشده | منطقه یا فیلترها را تغییر دهید |
| جزئی | برخی نتایج در دسترس‌اند؛ جستجو ناقص است | نتایج و هشدار را نمایش دهید |
| خطای اعتبارسنجی | جستجو حاوی پارامتری نامعتبر است | درخواست را اصلاح کنید |
| احراز هویت یا مجوزها | این دسترسی اجازه این جستجو را نمی‌دهد | حساب یا توکن را بررسی کنید |
| محدودیت یا عدم دسترسی | جستجو موقتا در دسترس نیست | رعایت دستورالعمل‌های واکنش |

برای ۴۲۹، دستورالعمل‌های سرویس و Retry-After را بررسی کنید. خطای ۴۰۰ نیاز به اصلاح آرگومان‌ها دارد؛ تکرار همان درخواست مشکل را حل نمی‌کند. تبدیل ۴۰۱ به تماس ناشناس خودکار اگر کاربر توکن داده نکنید.

[مرجع خطاهای API ROOTE](https://doc.roote.ai/roote-api/errors)

[وضعیت سرویس‌های ROOTE](https://status.roote.ai/)

## چهار وضعیت را قبل از انتشار بررسی کنید

پاسخ‌های آزمایشی کامل، خالی، جزئی و خطا و همچنین JSON نامعتبر و زمان گذشته را آماده کنید. پیام نمایش، نتایج حفظ‌شده و تعداد واکنش‌ها را بررسی کنید. آزمایش اساسی این است که نقص هرگز منجر به تأیید نبود سرویس‌ها نشود.

[اعمال این قوانین در یک دستیار هوش مصنوعی](https://www.roote.ai/fa/guides/chek-kardan-ye-dastgahi-ke-mobility-ha-ra-dar-hamkoli-ye-adress-peida-mikonad/)

[درک فرمت‌های داده‌های حمل‌ونقل](https://www.roote.ai/fa/guides/gtfs-gtfs-rt-va-gbfs-che-tafavotha/)

## پرسش‌های متداول

### آیا لیست خالی نبود توالت را ثابت می‌کند؟

خیر، فقط نشان می‌دهد برای این جستجو و منابع بررسی‌شده نتیجه‌ای بازنگشته.

### آیا می‌توان پاسخ جزئی نمایش داد؟

بله، اگر موجودیت‌های استفاده‌شده معتبر باشند و هشدارها و محدودیت‌ها حفظ شود.

### آیا باید هر خطا را دوباره اجرا کرد؟

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