طراحی و ساخت APIها در Postman
مدت زمان مطالعه: : 1 دقیقه
Postman چند مسیر مختلف برای طراحی و توسعه API در اختیار شما میگذارد. میتوانید با collectionها ساختار requestها را مشخص کنید، با Spec Hub مشخصات رسمی API را بنویسید، از specification یک collection بسازید و برای تست زودهنگام، mock server راهاندازی کنید.
طراحی API با collectionها #
در collectionهای HTTP میتوانید برای parameterها، headerها و body data نوع و ساختار تعریف کنید. این typeها به تیم شما و مصرفکنندگان API کمک میکنند request معتبر بفرستند و به جای خطا، پاسخ درست بگیرند.
برای نمونه میتوانید data type، مقدارهای مجاز و ساختار داده را برای بخشهای مختلف request تعریف کنید. Postman requestها را با این تعریفها اعتبارسنجی میکند، مشکلهای احتمالی را نشان میدهد و typeها را در مستندات collection هم نمایش میدهد.
ساخت specification از collection #
Postman میتواند از یک HTTP collection، specification با فرمت OpenAPI ۳.۰ تولید کند. این specification شامل pathها، componentها و بخشهای دیگر API است که بر اساس collection ساخته میشوند. اگر collection تغییر کند، میتوانید specification را با تغییرات جدید هماهنگ نگه دارید.
طراحی API با Spec Hub #
Spec Hub برای تعریف ساختار API با specification استفاده میشود. در Postman میتوانید specificationهایی مثل OpenAPI، AsyncAPI، protobuf ۲، protobuf ۳، GraphQL و Smithy ۲.۰ را مدیریت کنید.
هنگام ویرایش OpenAPI یا AsyncAPI، Postman خطاهای syntax و مشکلهای API governance را نشان میدهد. برای OpenAPI و AsyncAPI میتوانید پیشنمایش زنده مستنداتی را که از specification ساخته میشود در sidebar سمت راست ببینید.
ساخت collection از specification #
میتوانید از یک API specification، یک HTTP collection تولید کنید. Postman بر اساس specification، folderها، requestها و نمونه responseها را میسازد. اگر collection از OpenAPI ۳.۰ ساخته شده باشد، میتوانید آن را با تغییرات جدید specification همگام نگه دارید.
شبیهسازی API با mock server #
mock server به شما اجازه میدهد endpointهای API را بدون راهاندازی سرور واقعی شبیهسازی کنید. با ارسال request به mock server میتوانید رفتار API یا قابلیتهای جدید را قبل از آماده شدن نسخه production تست کنید.
به صورت پیشفرض، mock server پاسخهایی را برمیگرداند که در saved exampleها تعریف کردهاید. در صورت نیاز، میتوانید mock server را برای تولید پاسخهای dynamic هم تنظیم کنید.
چه زمانی از هر مسیر استفاده کنیم؟ #
- اگر تیم شما بیشتر با requestها و collectionها کار میکند، طراحی با collection و typeها سریعترین نقطه شروع است.
- اگر قرارداد رسمی API، استانداردسازی و governance برایتان مهم است، Spec Hub و specification انتخاب مناسبتری است.
- اگر backend هنوز آماده نیست یا میخواهید مصرفکنندهها زودتر تست کنند، mock server کمک میکند API را قبل از production شبیهسازی کنید.
این صفحه از نسخه زنده HTML مستندات Postman بازنویسی شده است، چون endpoint Markdown این صفحه در زمان مهاجرت محتوای صفحه را برنمیگرداند.
منبع آموزشی: Postman Docs، بازنویسی و سادهسازیشده برای کاربران فارسیزبان.
