API - Collections and organizing requests

جمع‌بندی سرفصل

Collection در Postman چیست؟

Collection در Postman مجموعه‌ای سازمان‌یافته از Request‌هاست که برای یک API، یک Microservice، یک Domain یا یک Business Flow کنار هم قرار می‌گیرند.
به زبان ساده، Collection مثل یک پوشه‌ی تست و مستندسازی است که داخلش می‌توان Requestها، Folderها، Authorization، Variables، Examples، Tests و Pre-request Script نگه داشت.

Collection فقط برای مرتب‌سازی ظاهری نیست؛ در عمل یکی از پایه‌های اصلی API Testing, Regression Testing, Collaboration, Documentation و Automation در Postman/Newman است.

چرا Collections مهم‌اند؟

اگر تستر درخواست‌ها را پراکنده، بدون دسته‌بندی و بدون نام‌گذاری درست نگه دارد، خیلی سریع این مشکلات پیش می‌آید:

• پیدا کردن Request درست سخت می‌شود

• اجرای Regression سخت و زمان‌بر می‌شود

• اعضای تیم متوجه نمی‌شوند هر Request برای چه سناریویی است

• مدیریت Environment، Token و Variable به‌هم می‌ریزد

• تست‌های E2E یا business flow قابل پیگیری نیستند

• مستندسازی و handover به بقیه‌ی تیم ضعیف می‌شود

پس Collection فقط ابزار نظم نیست؛ بخشی از test design discipline و test maintainability است.

Collection دقیقاً چه چیزهایی را می‌تواند در خودش نگه دارد؟

یک Collection می‌تواند شامل این موارد باشد:

• Request‌های API

• Folder برای دسته‌بندی درخواست‌ها

• Collection-level variables

• Authorization در سطح Collection

• Pre-request scripts

• Test scripts

• Examples

• Documentation / description

• Mock / monitor / runner execution context در بعضی سناریوها

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

منظور از organizing requests چیست؟

Organizing requests یعنی درخواست‌های API را به شکلی ساختاریافته و قابل‌فهم بچینی تا:

• پیدا کردن و اجرای آن‌ها راحت باشد

• ارتباط بین Requestها مشخص باشد

• سناریوهای business flow گم نشوند

• نگهداری تست‌ها در طول زمان ساده‌تر شود

یعنی تستر فقط نباید درخواست بزند؛ باید بداند چطور آن‌ها را ساختار بدهد.

روش‌های رایج برای organizing requests

چند مدل رایج برای سازمان‌دهی Requestها وجود دارد و هرکدام بسته به پروژه می‌تواند مناسب باشد.

1) دسته‌بندی بر اساس Resource / Entity

رایج‌ترین مدل این است که درخواست‌ها را بر اساس موجودیت‌های API دسته‌بندی کنیم.
مثلاً:

• Customers

  • Create Customer

  • Get Customer By Id

  • Update Customer

  • Delete Customer

• Accounts

  • Open Account

  • Get Account Details

  • Close Account

• Cards

  • Issue Card

  • Block Card

این مدل برای REST APIها خیلی رایج است چون با ساختار Resource-based سازگار است.

2) دسته‌بندی بر اساس Business Flow

گاهی بهتر است درخواست‌ها بر اساس سناریوی واقعی کسب‌وکار چیده شوند، نه صرفاً موجودیت‌ها.
مثلاً در یک سیستم بانکی:

• Customer Onboarding Flow

  • Create Customer

  • Verify Identity

  • Create Account

  • Issue Debit Card

یا:

• Money Transfer Flow

  • Login

  • Get Source Account

  • Transfer Money

  • Check Balance

  • Get Transaction History

این مدل برای E2E testing و سناریوهای واقعی خیلی مهم است.

3) دسته‌بندی بر اساس test type

گاهی می‌شود درخواست‌ها را بر اساس نوع تست جدا کرد:

• Smoke Tests

• Positive Tests

• Negative Tests

• Security Checks

• Regression

• Performance pre-checks

این مدل وقتی خوب است که تیم بخواهد اجرای تست‌ها را بر اساس هدف تست مدیریت کند.

4) دسته‌بندی بر اساس version / environment / service

در بعضی پروژه‌ها، APIها نسخه‌های مختلف دارند یا چند سرویس مجزا دارند.
مثلاً:

• Customer Profile API v1

• Customer Profile API v2

• Authentication Service

• Card Service

• Notification Service

این مدل برای معماری‌های microservice و پروژه‌های بزرگ‌تر خیلی کاربردی است.

ساختار خوب Collection چه شکلی است؟

یک Collection خوب معمولاً این ویژگی‌ها را دارد:

1) اسم‌گذاری شفاف

اسم Collection، Folder و Request باید دقیق و بدون ابهام باشد.

بد:

• test1

• new api

• request 4

خوب:

• Customer Profile API

• Create Customer – Valid Request

• Update Customer – Invalid National Code

• Transfer Money – Insufficient Balance

اسم خوب باعث می‌شود هم خودت، هم تیم سریع بفهمند این درخواست دقیقاً چه کاری می‌کند.

2) تفکیک سناریوی Positive و Negative

یکی از اشتباه‌های رایج این است که همه‌چیز در یک فولدر قاطی شود.
بهتر است برای هر API یا Business Flow، سناریوهای Positive و Negative قابل‌تشخیص باشند.

مثلاً:

• Create Customer

  • Valid Request

  • Missing Required Field

  • Invalid Content-Type

  • Duplicate National Code

این ساختار برای Regression و Bug Reproduction خیلی مفید است.

3) استفاده از Folder

Folder فقط برای زیبایی نیست.
با Folder می‌توان:

• درخواست‌های مرتبط را کنار هم نگه داشت

• Authorization یا variables خاص را روی همان فولدر اعمال کرد

• اجرای دسته‌ای سناریوهای مرتبط را ساده‌تر کرد

مثلاً:

• Authentication

• Customer CRUD

• Money Transfer

• Negative Cases

• Admin-only APIs

4) نگه داشتن Pre-request و Test scripts در جای درست

اگر همه‌ی اسکریپت‌ها را در هر Request جداگانه بنویسی، هم نگهداری سخت می‌شود، هم تکرار بالا می‌رود.

ساختار بهتر این است:

• چیزهای مشترک در سطح Collection یا Folder

• چیزهای خاص هر سناریو در سطح Request

مثلاً:

• گرفتن token یا تنظیم common headers در سطح Collection/Folder

• assertion خاص همان API در سطح Request

5) جدا کردن Environment-specific داده از خود Request

نباید base URL، token، customer id یا مقادیر محیطی را hard-code کنی.
بهتر است از variables استفاده کنی تا همان Collection روی dev / test / stage / preprod قابل اجرا باشد.

مثلاً:

• {{baseUrl}}

• {{accessToken}}

• {{customerId}}

فرق Collection و Folder و Request

Collection

سطح بالای سازمان‌دهی است؛ مثل ظرف اصلی تست‌های یک API یا یک دامنه.

Folder

زیرمجموعه‌ی Collection برای دسته‌بندی درخواست‌های مرتبط.

Request

یک درخواست مشخص HTTP با method + URL + headers + body + tests

مثال:

Collection:

Customer Profile API

Folder:

Customer CRUD

Requests:

• Create Customer

• Get Customer By Id

• Update Customer

• Delete Customer

کاربرد Collection در Automation / Runner / Newman

یکی از دلایل مهم ساختار درست Collection این است که بعداً بتوانی آن را راحت اجرا و اتومات کنی.

وقتی Collection خوب سازمان‌دهی شده باشد:

• می‌توانی با Collection Runner فقط یک فولدر خاص را اجرا کنی

• می‌توانی آن را با Newman در CLI / CI/CD اجرا کنی

• می‌توانی data-driven execution داشته باشی

• می‌توانی Regression pack و Smoke pack بسازی

پس Collection فقط برای تست دستی نیست؛ مقدمه‌ی تست اتومات هم هست.

کاربرد Collection در Documentation و Team Collaboration

یک Collection خوب می‌تواند نقش living documentation هم داشته باشد.
یعنی وقتی کسی Collection را باز می‌کند، فقط request نمی‌بیند؛ می‌فهمد:

• API چه endpointهایی دارد

• سناریوهای مهم کدام‌اند

• چه headerهایی لازم‌اند

• چه bodyهایی معتبر یا نامعتبرند

• چه flowهایی در سیستم وجود دارد

برای همین، Collection در تیم‌های واقعی هم ابزار تست است، هم ابزار دانش تیمی.

اشتباه‌های رایج در organizing requests

1) نگه داشتن همه‌ی درخواست‌ها در یک Collection شلوغ و بدون ساختار

نتیجه:

• پیدا کردن سناریو سخت می‌شود

• Regression کند می‌شود

• اشتباه انسانی بالا می‌رود

2) نام‌گذاری مبهم

مثل:

• test

• customer2

• api final

این‌ها بعداً عملاً بی‌مصرف می‌شوند.

3) قاطی کردن محیط با منطق تست

مثلاً داخل خود Request بنویسی:

• آدرس stage

• token واقعی

• id ثابت

این کار باعث می‌شود تست قابل‌استفاده‌ی مجدد نباشد.

4) نداشتن ساختار برای Negative cases

اگر فقط happy pathها را بچینی، Collection از دید تست ناقص است.

5) تکرار زیاد اسکریپت‌ها و headerها

اگر در هر request دوباره همان Authorization یا همان base URL را بنویسی، هم maintenance سخت می‌شود، هم خطا زیاد می‌شود.

نگاه آزمونی به این سرفصل

اگر در آزمون از تو پرسیدند Collections and organizing requests چیست، جواب خوب فقط این نیست که بگویی:

Collection یعنی مجموعه‌ای از requestها در Postman.

این تعریف خیلی حداقلی است.
جواب خوب باید بگوید Collection برای این‌ها استفاده می‌شود:

• Grouping requests

• Organizing by resource / flow / test type

• Reusability

• Regression execution

• Collaboration

• Documentation

• Running requests in sequence

• Applying common auth / variables / scripts

• Maintainability

اهمیت این سرفصل برای Backend Tester

یک Backend Tester باید بتواند Requestها را طوری سازمان‌دهی کند که:

• سناریوهای API گم نشوند

• Regression قابل‌اجرا باشد

• تست‌های negative و positive از هم قابل‌تشخیص باشند

• اجرای تست در Postman Runner / Newman ساده شود

• داده‌های محیطی قابل مدیریت باشند

• تیم بتواند Collection را بخواند، بفهمد و reuse کند

این سرفصل مستقیماً در API Test Design, Test Asset Management, Automation readiness و team collaboration اثر دارد.

نکته امتحانی مهم

در پاسخ امتحانی حتماً بین این سه چیز تفکیک بگذار:

• Collection = ظرف اصلی و سطح بالای سازمان‌دهی

• Folder = دسته‌بندی سناریوها یا endpointها داخل Collection

• Request = یک فراخوانی مشخص API

و حتماً اشاره کن که organizing requests فقط مرتب‌سازی ظاهری نیست؛ بلکه برای maintainability, regression, documentation, reusability و automation مهم است.

نمونه پاسخ کامل کوتاه

در Postman، Collection مجموعه‌ای سازمان‌یافته از Requestهاست که برای یک API، یک Business Flow یا یک Microservice ساخته می‌شود و می‌تواند شامل Folder، Authorization، Variables، Pre-request scripts، Test scripts و Examples باشد. Organizing requests یعنی درخواست‌ها به شکلی ساختار داده شوند که اجرای Regression، مدیریت سناریوهای positive/negative، مستندسازی، همکاری تیمی و اجرای تست با Runner/Newman ساده‌تر شود. این سازمان‌دهی می‌تواند بر اساس Resource، Business Flow، Test Type یا Service/Version انجام شود.

کلیدواژه‌ها

Collection Folder Request Request Organization Grouping Business Flow Resource-based grouping Positive/Negative scenarios Reusability Maintainability Regression Pack Smoke Pack Collection Runner Newman Collection-level Authorization Collection Variables Folder-level Scripts Request Naming Documentation Collaboration

Collection (مجموعه‌ای سازمان‌یافته از Requestها در Postman): برای نگهداری، اجرای مجدد، مستندسازی و مدیریت تست‌های API استفاده می‌شود.

Folder (زیرمجموعه‌ای داخل Collection برای دسته‌بندی Requestها): برای جدا کردن endpointها، business flowها یا سناریوهای مثبت/منفی استفاده می‌شود.

Request (یک فراخوانی مشخص API شامل method، URL، headers، body و tests): واحد اصلی اجرای تست API است.

Request Organization (سازمان‌دهی منطقی درخواست‌ها): برای خوانایی، نگهداری، اجرای تست و جلوگیری از آشفتگی در Collection استفاده می‌شود.

Grouping (دسته‌بندی Requestها بر اساس یک معیار مشخص): می‌تواند بر اساس Resource، Business Flow، Version یا Test Type باشد.

Business Flow (زنجیره‌ای از Requestها که یک سناریوی واقعی کسب‌وکار را تشکیل می‌دهند): در E2E testing و طراحی سناریوهای واقعی استفاده می‌شود.

Resource-based grouping (دسته‌بندی بر اساس موجودیت‌های API مثل Customer یا Account): در REST APIها برای مرتب‌سازی endpointهای مرتبط کاربرد دارد.

Positive/Negative scenarios (سناریوهای معتبر و نامعتبر): برای طراحی Regression و پوشش بهتر تست‌ها در Collection باید از هم قابل‌تفکیک باشند.

Reusability (قابلیت استفاده‌ی مجدد از Requestها، اسکریپت‌ها و ساختار تست): با استفاده از Collection، Variables و Authorization مشترک به دست می‌آید.

Maintainability (قابلیت نگهداری و تغییر آسان تست‌ها در طول زمان): ساختار درست Collection باعث می‌شود تغییر endpointها، headerها یا سناریوها ساده‌تر مدیریت شود.

Regression Pack (مجموعه‌ای از تست‌های تکرارشونده برای اطمینان از خراب نشدن قابلیت‌های قبلی): می‌تواند به‌صورت Collection یا Folder سازمان‌دهی شود.

Smoke Pack (مجموعه‌ای کوچک از تست‌های حیاتی برای اطمینان از سالم بودن اولیه سیستم): معمولاً در یک Folder یا Collection مجزا نگه‌داری می‌شود.

Collection Runner (ابزار اجرای دسته‌ای Requestها در Postman): برای اجرای سناریوهای زنجیره‌ای، regression و data-driven tests استفاده می‌شود.

Newman (نسخه CLI اجرای Collectionهای Postman): برای اجرای Collection در terminal, CI/CD و automation pipeline استفاده می‌شود.

Collection-level Authorization (تعریف Authorization در سطح Collection): برای جلوگیری از تکرار headerهای احراز هویت در همه‌ی Requestها استفاده می‌شود.

Collection Variables (متغیرهای تعریف‌شده در سطح Collection): برای مقادیر مشترک مثل baseUrl، customerId یا default token استفاده می‌شود.

Folder-level Scripts (اسکریپت‌هایی که در سطح Folder تعریف می‌شوند): برای منطق مشترک یک دسته از Requestها، مثل گرفتن token یا assertionهای مشابه استفاده می‌شوند.

Request Naming (نام‌گذاری دقیق و معنادار Requestها): برای خوانایی، traceability و فهم سریع سناریوی تست اهمیت دارد.

Documentation (مستندسازی Requestها، توضیح سناریوها و نمونه‌ها): Collection می‌تواند نقش living documentation برای API و تست را ایفا کند.

Collaboration (همکاری تیمی روی Collectionها): وقتی Collection ساختار خوب و توضیح مناسب داشته باشد، توسعه‌دهنده، تستر و تحلیل‌گر راحت‌تر می‌توانند از آن استفاده کنند.