API - Versioning Approaches (URL, Header, Query Parameter, Media Type)

API Versioning چیست؟

API Versioning یعنی مدیریت نسخه‌های مختلف یک API به‌گونه‌ای که تغییرات جدید باعث خراب شدن Clientهای قدیمی نشود. با Versioning می‌توان نسخه‌های مختلف API را به‌صورت هم‌زمان پشتیبانی کرد تا سیستم‌های قدیمی بدون تغییر به کار خود ادامه دهند و Clientهای جدید از قابلیت‌های نسخه جدید استفاده کنند.

در سیستم‌های بزرگ و بانکی، حذف یا تغییر مستقیم یک API بدون Versioning می‌تواند باعث از کار افتادن Mobile App، Web Application یا سرویس‌های وابسته شود؛ بنابراین Versioning یکی از اصول مهم Backward Compatibility است.

چرا Versioning مهم است؟

در توسعه API، ممکن است:

• فیلد جدید اضافه شود.

• نام یک فیلد تغییر کند.

• ساختار Response تغییر کند.

• Business Logic تغییر کند.

• فیلدی حذف شود.

اگر این تغییرات بدون Versioning انجام شوند، Clientهای قدیمی دیگر قادر به استفاده از API نخواهند بود.

روش‌های رایج API Versioning

URL Versioning

در این روش شماره نسخه داخل URL قرار می‌گیرد.

مثال:

GET /api/v1/customers/123

نسخه جدید:

GET /api/v2/customers/123

مزایا

• ساده و قابل فهم

• مشاهده نسخه در URL

• مناسب برای مستندسازی و Swagger

• رایج‌ترین روش در REST API

معایب

• با هر نسخه URL تغییر می‌کند.

• Endpointهای بیشتری ایجاد می‌شود.

Header Versioning

در این روش نسخه داخل Header ارسال می‌شود.

مثال:

GET /customers/123

API-Version: 2

یا

X-API-Version: 2

مزایا

• URL ثابت باقی می‌ماند.

• نسخه از Resource جدا می‌شود.

• Endpoint تغییر نمی‌کند.

معایب

• در URL قابل مشاهده نیست.

• تست و Debug کمی سخت‌تر است.

Media Type Versioning (Accept Header Versioning)

در این روش نسخه داخل Header Accept مشخص می‌شود.

مثال:

Accept: application/vnd.bank.customer.v2+json

مزایا

• کاملاً مطابق REST

• نسخه در Representation مشخص می‌شود.

• URL ثابت باقی می‌ماند.

معایب

• پیچیده‌تر از URL Versioning

• خوانایی کمتر

• برای افراد تازه‌کار سخت‌تر است.

Query Parameter Versioning

در این روش نسخه به‌صورت پارامتر ارسال می‌شود.

مثال:

GET /customers/123?version=2

مزایا

• پیاده‌سازی ساده

• URL تقریباً ثابت

معایب

• کمتر استفاده می‌شود.

• از نظر REST بهترین روش محسوب نمی‌شود.

Backward Compatibility

Backward Compatibility چیست؟

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

مثلاً:

نسخه اول:

{
  "firstName": "Ali"
}

نسخه دوم:

{
  "firstName": "Ali",
  "nationalCode": "0012345678"
}

اگر فقط فیلد جدید اضافه شود، معمولاً Backward Compatible است.

اما اگر:

{
  "name": "Ali"
}

به‌جای firstName برگردد، احتمالاً Client قدیمی دچار Failure می‌شود.

Breaking Change

Breaking Change چیست؟

هر تغییری که باعث شود Client قبلی دیگر نتواند با API کار کند.

نمونه‌ها:

• حذف فیلد

• تغییر نام فیلد

• تغییر نوع داده

• تغییر ساختار Response

• تغییر Status Code

• حذف Endpoint

• تغییر Business Rule

این تغییرات معمولاً نیاز به نسخه جدید API دارند.

Non-breaking Change

تغییراتی که Clientهای قدیمی را خراب نمی‌کنند.

مثلاً:

• اضافه شدن یک فیلد اختیاری

• اضافه شدن Endpoint جدید

• اضافه شدن Header جدید

• اضافه شدن مقدار جدید به Enum (در بعضی طراحی‌ها)

Deprecated API

گاهی نسخه قدیمی حذف نمی‌شود، بلکه Deprecated می‌شود.

یعنی:

• هنوز کار می‌کند.

• ولی توصیه می‌شود Clientها به نسخه جدید مهاجرت کنند.

• معمولاً زمان حذف نیز اعلام می‌شود.

Version Migration

بعد از انتشار نسخه جدید:

• نسخه قدیمی مدتی پشتیبانی می‌شود.

• Clientها به نسخه جدید منتقل می‌شوند.

• در نهایت نسخه قدیمی حذف می‌شود.

تست Versioning

Backend Tester باید بررسی کند:

• هر نسخه Contract مخصوص خودش را دارد.

• نسخه قدیمی هنوز درست کار می‌کند.

• نسخه جدید رفتار مورد انتظار را دارد.

• تغییرات فقط در نسخه جدید اعمال شده‌اند.

• Response نسخه‌ها با Contract همان نسخه سازگار است.

• Swagger/OpenAPI هر نسخه مستقل باشد.

• Client قدیمی دچار Failure نشود.

سناریوهای تست مهم

باید تست شوند:

• درخواست بدون Version

• Version نامعتبر

• Version پشتیبانی‌نشده

• Version قدیمی

• Version جدید

• Header Version اشتباه

• URL Version اشتباه

• Contract Version Mismatch

• Backward Compatibility

• Deprecated API

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

Backend Tester باید بتواند:

• تشخیص دهد API از چه روش Versioning استفاده می‌کند.

• بین URL Versioning، Header Versioning، Media Type Versioning و Query Parameter Versioning تفاوت قائل شود.

• Backward Compatibility را تست کند.

• Breaking Change را شناسایی کند.

• رفتار نسخه‌های مختلف API را با Contract همان نسخه مقایسه کند.

• اطمینان حاصل کند که Release جدید باعث خرابی Clientهای قدیمی نشده است.

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

در پاسخ امتحانی فقط نگویید:

Versioning یعنی نسخه‌بندی API.

پاسخ کامل باید این کلیدواژه‌ها را داشته باشد:

Backward Compatibility, Breaking Change, Non-breaking Change, Contract, URL Versioning, Header Versioning, Media Type Versioning, Query Parameter Versioning, Deprecated API, Migration

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

API Versioning روشی برای مدیریت نسخه‌های مختلف API است تا تغییرات جدید باعث از کار افتادن Clientهای قدیمی نشود. رایج‌ترین روش‌ها شامل URL Versioning، Header Versioning، Media Type Versioning و Query Parameter Versioning هستند. مهم‌ترین هدف Versioning حفظ Backward Compatibility است. تغییراتی مانند حذف فیلد، تغییر نام فیلد یا تغییر ساختار Response از نوع Breaking Change هستند و معمولاً نیاز به نسخه جدید API دارند. Backend Tester باید نسخه‌های مختلف را از نظر Contract، Compatibility و رفتار API به‌صورت مستقل تست کند.

کلیدواژه‌ها

API Versioning URL Versioning Header Versioning Media Type Versioning Accept Header Query Parameter Versioning Backward Compatibility Breaking Change Non-breaking Change Deprecated API Migration API Contract Contract Compatibility Swagger Versioning OpenAPI Specification Client Compatibility

API Versioning (مدیریت هم‌زمان نسخه‌های مختلف API): برای جلوگیری از خراب شدن Clientهای قدیمی هنگام انتشار نسخه جدید استفاده می‌شود.

URL Versioning (قرار دادن شماره نسخه در URL): رایج‌ترین روش Versioning در REST API است.

Header Versioning (ارسال نسخه در Header): باعث ثابت ماندن URL و جداسازی نسخه از Resource می‌شود.

Media Type Versioning (مشخص کردن نسخه در Header Accept): نسخه را در نوع محتوای Response مشخص می‌کند و مطابق معماری REST است.

Accept Header (Header مشخص‌کننده نوع Response مورد انتظار): در Media Type Versioning برای تعیین نسخه نیز استفاده می‌شود.

Query Parameter Versioning (ارسال نسخه به‌صورت پارامتر): روشی ساده ولی کم‌کاربردتر برای مدیریت نسخه API است.

Backward Compatibility (سازگاری با نسخه‌های قبلی): تضمین می‌کند Clientهای قدیمی بعد از انتشار نسخه جدید همچنان بدون تغییر کار کنند.

Breaking Change (تغییری که باعث خرابی Client قبلی شود): مانند حذف فیلد، تغییر نام فیلد، تغییر نوع داده یا حذف Endpoint.

Non-breaking Change (تغییری که Clientهای قبلی را خراب نکند): مانند اضافه کردن فیلد اختیاری یا Endpoint جدید.

Deprecated API (نسخه‌ای که هنوز فعال است اما قرار است حذف شود): برای اطلاع‌رسانی و مهاجرت تدریجی Clientها استفاده می‌شود.

Migration (فرآیند انتقال Clientها به نسخه جدید): برای حذف تدریجی نسخه‌های قدیمی انجام می‌شود.

API Contract (توافق بین Client و Server برای هر نسخه API): باید برای هر Version مستقل حفظ شود.

Contract Compatibility (سازگاری Contract بین نسخه‌ها): برای بررسی اینکه تغییرات باعث Failure در Clientهای قبلی نشده‌اند استفاده می‌شود.

Swagger Versioning (مستندسازی نسخه‌های مختلف در Swagger): برای تست و نگهداری مستقل هر نسخه API کاربرد دارد.

OpenAPI Specification (استاندارد مستندسازی API): مشخص می‌کند هر نسخه API چه Endpoint، Schema و Contractی دارد.

Client Compatibility (سازگاری Client با نسخه API): بررسی می‌کند Clientهای قدیمی و جدید با نسخه مناسب API بدون Failure کار می‌کنند.

توضیح کوتاه پست

مرور فشرده‌ی API Versioning با تمرکز بر روش‌های URL، Header، Media Type و Query Parameter، همراه با مفاهیم Backward Compatibility، Breaking Change و مدیریت نسخه‌های مختلف API.

تگ‌ها

#APITesting
#RESTAPI
#Versioning
#BackendTesting
#OpenAPI