منسوخ کردن API های REST: راهنمای توسعه دهنده

Summarize this content to 400 words in Persian Lang
همه چیزهای خوب در نهایت به پایان می رسند – و گاهی اوقات چیزهای بدی مانند انتخاب های منفور طراحی API ما نیز به پایان می رسد. متأسفانه برای ما برنامه نویسان API، شما همیشه نمی توانید نقطه پایانی قدیمی خود را حذف کنید و از نو شروع کنید – باید یک استراتژی انحلال داشته باشید تا مصرف کنندگان API شما غافل نشوند.

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

منسوخ کردن یک API به چه معناست؟

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

چرا باید یک API را منسوخ کنید

منسوخ کردن APIها برای حفظ یک سیستم تمیز، کارآمد و ایمن ضروری است. در اینجا چند دلیل وجود دارد که چرا ممکن است یک API را منسوخ کنید:

بهبودهای امنیتی: API های قدیمی ممکن است دارای آسیب پذیری هایی باشند که در نسخه های جدیدتر برطرف شده اند.

بهبود عملکرد: API های جدیدتر ممکن است عملکرد بهتری ارائه دهند.

ارتقاء ویژگی ها: معرفی ویژگی‌های جدید که با نسخه‌های قدیمی‌تر سازگار نیستند.

سربار تعمیر و نگهداری: کاهش بار پشتیبانی از APIهای قدیمی.

رعایت مقررات: اطمینان از مطابقت APIها با استانداردهای قانونی و انطباق فعلی.

مراحل حذف API

قبل از اینکه بتوانیم وارد فرآیند منسوخ کردن یک API شویم، در اینجا مروری اجمالی از مراحل حذف API داریم – فقط برای اینکه در آینده در مورد اصطلاحات واضح باشیم.

منسوخ شدن API معمولاً از جدول زمانی زیر پیروی می کند:

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

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

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

روز غروب آفتاب: امیدواریم در این مرحله آخرین کاربران خود را از API منسوخ شده خارج کرده باشید. می توانید حذف API قدیمی را شروع کنید. معمولاً کار خوبی است که اسناد API را پشت سر بگذارید (کاربران ممکن است آن را نشانه گذاری کنند)، اما آن را به روز کنید تا وضعیت غروب آفتاب را منعکس کند.

شرایط کلیدی

اعلامیه منسوخ شدن: هشداری که به کاربران در مورد قطع آینده ارائه می شود.

دوره مهلت: بازه زمانی که در طی آن API منسوخ شده قبل از بازنشستگی عملیاتی می شود.

گزینه های جایگزین: اطلاعات مربوط به نسخه های جدیدتر یا سایر API هایی که باید به جای آن استفاده شوند.

منسوخ شدن در مقابل غروب یک API

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

منسوخ شدن: دوره ای که به کاربران هشدار داده می شود که API در آینده متوقف خواهد شد. API همچنان فعال است اما دیگر برای استفاده توصیه نمی شود.

غروب آفتاب: نقطه ای که در آن API دیگر در دسترس نیست. کاربران باید به نسخه‌ها یا جایگزین‌های جدیدتر مهاجرت کرده باشند.

ملاحظات فنی برای منسوخ کردن یک API

هنگام منسوخ کردن یک API (و برنامه ریزی برای جایگزینی)، جنبه های فنی زیر را در نظر بگیرید:

نظارت بر استفاده: پیگیری کنید که هر چند وقت یک‌بار از API که می‌خواهید منسوخ کنید برای سنجش تأثیر منسوخ استفاده می‌شود.

استراتژی نسخه سازی: یک استراتژی نسخه‌سازی را برای روان‌تر کردن انتقال اجرا کنید..

سازگاری با عقب: انتقال از نقطه پایانی قدیمی به نقطه پایانی جدید را آسان کنید. یک API کاملاً متفاوت باعث می شود کاربران تمایلی به مهاجرت نداشته باشند و غروب API را برای شما سخت تر می کند.

به روز رسانی اسناد: تمام اسناد API را با اعلامیه های منسوخ شدن به روز نگه دارید. بهترین مکان برای انجام این کار معمولاً در سند OpenAPI شما است (نحوه زیر را ببینید).

انواع حذف API

Deprecation همیشه به یک API کامل اشاره نمی کند – در واقع شما می توانید در واقع نقاط پایانی و حتی ویژگی های نقاط پایانی را منسوخ کنید. این کار از ایجاد یک نسخه کاملاً جدید از API خود جلوگیری می کند – حذف مشتریان از نسخه های قدیمی API شما می تواند بسیار چالش برانگیز باشد. توجه داشته باشید که احتمالاً همان مراحل بالا را دنبال خواهید کرد، اما احتمالاً با دقت کمتری (مثلاً منسوخ شدن یک پارامتر ممکن است در یک یادداشت اصلاحیه عمومی اعلام شود).

با توجه به رواج OpenAPI و استفاده از آن در پلتفرم‌های مستندسازی API – در اینجا نمونه‌هایی از نحوه انجام انواع مختلف انحلال‌ها وجود دارد که اکثر ابزارهای OpenAPI باید از عهده آن برآیند. یکی از ویژگی‌های گمشده در OpenAPI 3.1 این است که هیچ راهی رسمی برای راهنمایی کاربران به آخرین نسخه API شما وجود ندارد – علیرغم اینکه مشخصاتی سال‌ها پیش ارائه شده بود، بنابراین ما باید آن را در توضیحات هک کنیم.

چگونه یک نقطه پایانی API را منسوخ کنیم

منسوخ کردن یک نقطه پایانی API شامل به روز رسانی اسناد و مشخصات API شما برای نشان دادن منسوخ شدن است.

paths:
/v1/old-endpoint:
get:
deprecated: true
summary: “Deprecated endpoint for retrieving user data”
description:
“This endpoint is deprecated and will be removed on YYYY-MM-DD. Use
/v2/new-endpoint instead.”
responses:
“200”:
description: Successful response

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

تنظیم کنید deprecated: true: این نشان می دهد که نقطه پایانی منسوخ شده است.

به روز رسانی summary و description: یک پیام واضح در مورد منسوخ شدن و گزینه های جایگزین درج کنید.

یک جدول زمانی ارائه دهید: می توانید از آن استفاده و مستند کنید deprecation هدر

چگونه یک نسخه API کامل را منسوخ کنیم

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

openapi: 3.0.0
info:
version: “1.0.0”
title: “Deprecated API Version”
description:
“Version 1.0.0 is deprecated and will be retired on YYYY-MM-DD. Please
upgrade to version 2.0.0.”
x-deprecation: “2023-11-11T23:59:59Z”
paths:
/v1/endpoint:
get:
summary: “Endpoint in deprecated API version”
responses:
“200”:
description: Successful response

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

اضافه کنید x-deprecated: در info بخش: پسوند سفارشی برای نشان دادن تاریخ منسوخ شدن API. این می تواند برای مولدهای سرویس گیرنده API مفید باشد تا از مزایای آن برای هشدار دادن به کاربران استفاده کنند.

به روز رسانی description: وضعیت منسوخ شدن را به وضوح بیان کنید و کاربران را به نسخه جدید راهنمایی کنید.

چگونه یک فیلد API را منسوخ کنیم

گاهی اوقات، فقط یک فیلد خاص در یک پاسخ یا درخواست API باید منسوخ شود.

components:
schemas:
User:
type: object
properties:
id:
type: string
username:
type: string
fullName:
type: string
deprecated: true
description:
“This field is deprecated and will be removed on YYYY-MM-DD. Use
‘firstName’ and ‘lastName’ instead.”
firstName:
type: string
lastName:
type: string

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

تنظیم کنید deprecated: true در زمین: نشان می دهد که این فیلد دیگر نباید استفاده شود.

به روز رسانی توضیحات فیلد: جزئیات مربوط به منسوخ شدن و گزینه های جایگزین را ارائه دهید.

سازگاری به عقب را حفظ کنید: میدان را در طول دوره استهلاک عملیاتی نگه دارید.

سرصفحه حذف HTTP

HTTP Deprecation هدر برای اطلاع رسانی به مشتریان مبنی بر منسوخ شدن یک منبع استفاده می شود. ما یک راهنمای کامل برای این هدر داریم، اما در اینجا یک مرور سریع وجود دارد:

چگونه کار می کند

طبق آخرین پیش نویس پیشنهادی، فیلد باید یک تاریخ RFC 9651 باشد که در زمان یونیکس بیان می شود. تاریخ می تواند در گذشته باشد (API قبلاً منسوخ شده است) یا می تواند در آینده باشد (API در این تاریخ منسوخ خواهد شد). در اینجا یک مثال برای API است که جمعه، 30 ژوئن 2023 در ساعت 23:59:59 UTC منسوخ شده است:

Deprecation: @1688169599

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

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

پیاده سازی نیز بسیار ساده است:

const express = require(“express”);
const app = express();

app.get(“/v1/old-endpoint”, (req, res) => {
const deprecationDate = new Date().now();
res.set(“Deprecation”, deprecationDate);
res.json({ message: “This endpoint is deprecated.” });
});

app.listen(3000, () => console.log(“Server running on port 3000”));

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

پشتیبانی چارچوب برای Deprecation API

بسیاری از چارچوب‌های API تا حدی از حذف API پشتیبانی می‌کنند – معمولاً فقط نقاط پایانی منسوخ شده را پوشش می‌دهند. با توجه به اینکه بسیاری از فریم‌ورک‌ها مشخصات OpenAPI را برای شما تولید می‌کنند، اغلب حاشیه‌نویسی‌هایی ارائه می‌کنند که به مشخصات تولید شده متصل می‌شوند.

Fastify (جاوا اسکریپت/تایپ اسکریپت)

چارچوب های API زیادی برای JS/TS وجود دارد، اما Fastify یکی از موارد مورد علاقه ما است. Fastify به شما امکان می دهد متادیتای سفارشی را برای مسیرها تنظیم کنید و هنگامی که با افزونه fastify-swagger ترکیب می شود، می توانید مسیرها را به عنوان منسوخ شده در اسناد OpenAPI خود علامت بزنید.

const fastify = require(“fastify”)();
fastify.register(require(“fastify-swagger”), {
exposeRoute: true,
routePrefix: “/documentation”,
swagger: {
info: {
title: “API Documentation”,
version: “1.0.0”,
},
},
});

fastify.get(
“/v1/old-endpoint”,
{
schema: {
deprecated: true,
summary: “Deprecated endpoint”,
description:
“This endpoint is deprecated and will be removed in the future.”,
response: {
200: {
type: “object”,
properties: {
message: { type: “string” },
},
},
},
},
},
async (request, reply) => {
reply.header(“Deprecation”, “true”);
return { message: “This endpoint is deprecated.” };
},
);

fastify.listen(3000, (err) => {
if (err) throw err;
console.log(“Server running on port 3000”);
});

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

اگر می‌خواهید نمونه‌های فریمورک Node بیشتری ببینید – 6 نمونه فریمورک دیگر را که ایجاد کردیم، بررسی کنید.

بهار (جاوا)

Spring Framework به رسمیت می شناسد @Deprecated حاشیه نویسی در سطح متد یا کلاس. هنگامی که با ابزارهای ادغام Swagger مانند Springfox یا SpringDoc ترکیب می شوند، API های منسوخ شده به طور خودکار به این صورت مستند می شوند.

@RestController
public class UserController {

@Deprecated
@GetMapping(“/v1/old-endpoint”)
public ResponseEntity<String> oldEndpoint() {
return ResponseEntity.ok(“This endpoint is deprecated.”);
}

@GetMapping(“/v2/new-endpoint”)
public ResponseEntity<String> newEndpoint() {
return ResponseEntity.ok(“This is the new endpoint.”);
}
}

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نت

استفاده کنید [Obsolete] برای علامت‌گذاری کنترل‌کننده‌ها یا روش‌های عمل به‌عنوان منسوخ شده، مشخص شود. ابزارهایی مانند Swashbuckle (برای ادغام OpenAPI) این ویژگی را تشخیص داده و اسناد API را بر اساس آن به روز می کنند.

[HttpGet(“v2/some-endpoint”)] public IActionResult NewEndpoint()
{
return Ok(“This is the new endpoint.”);
}
}

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

چارچوب استراحت جنگو (پایتون)

DRF از حذف از طریق بسته های شخص ثالث مانند drf-yasg برای اسناد Swagger پشتیبانی می کند که پارامتر منسوخ شده را تشخیص می دهد.

from rest_framework.decorators import api_view
from rest_framework.response import Response
from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(method=’get’, deprecated=True)
@api_view([‘GET’])
def old_endpoint(request):
return Response({‘message’: ‘This endpoint is deprecated.’})

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

اگر از ابزار مدیریت API استفاده کنم چه می شود؟

اگر از یک ابزار مدیریت API یا یک دروازه API مدیریت شده استفاده می کنید – احتمالاً این پلتفرم دارای نوعی عملکرد منسوخ است. در اینجا چند ابزار رایج و نحوه منسوخ کردن یک API با آنها آورده شده است

یک API Zuplo را منسوخ کنید

Zuplo به طور بومی توسط OpenAPI پشتیبانی می شود و همچنین با استفاده از Typescript کاملاً قابل برنامه ریزی است. این بدان معناست که نمونه‌های حذف OpenAPI و اجرای هدر منسوخ از بالا کاملاً با Zuplo سازگار هستند! پورتال توسعه‌دهنده شما به‌طور خودکار به‌روزرسانی می‌شود تا منسوخ شدن را منعکس کند.

یک Kong API را منسوخ کنید

Kong از افزودن هدرهای سفارشی از طریق افزونه ها پشتیبانی می کند.

plugins:
– name: response-transformer
config:
add:
headers:
– “Deprecation: @1688169599″

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

Apigee API را منسوخ کنید

Apigee به شما این امکان را می دهد که هدرها را از طریق خط مشی ها تنظیم کنید. من پیشاپیش بابت XML عذرخواهی می کنم.

async=”false” continueOnError=”false” enabled=”true” name=”AddDeprecationHeader”>

name=”Deprecation”>@1688169599

true

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نمونه هایی از حذف موفقیت آمیز API

Twitter API نسخه 1 به نسخه 2 انتقال

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

استراتژی های کلیدی:

ارتباط جامع: به‌روزرسانی‌های منظم از طریق وبلاگ‌ها، ایمیل‌ها و انجمن‌های توسعه‌دهندگان.

دوره پشتیبانی تمدید شده: زمان کافی برای مهاجرت توسعه دهندگان فراهم شده است.

مستندات قوی: راهنماها و آموزش های دقیق برای API جدید.

درس هایی از خرابی API Deprecation

Google Reader API Shutdown

هنگامی که گوگل سرویس Google Reader را بازنشسته کرد، بسیاری از برنامه های کاربردی متکی به API آن بدون جایگزین باقی ماندند که منجر به اختلال قابل توجهی شد.

چه اشتباهی رخ داد:

اطلاعیه کوتاه: استهلاک و خاموشی به سرعت اتفاق افتاد.

فقدان جایگزین: جایگزینی مستقیم یا مسیر مهاجرت ارائه نشده است.

ارتباط ناکافی: کاربران و توسعه دهندگان از این تصمیم چشم پوشی کردند.

غذای آماده:

زمان کافی را فراهم کنید: همیشه به کاربران زمان کافی برای سازگاری بدهید.

گزینه های جایگزین را ارائه دهید: کاربران را به سایر سرویس ها یا API ها راهنمایی کنید.

ارتباط باز را حفظ کنید: جامعه توسعه دهندگان را در هر مرحله مطلع نگه دارید.

نتیجه گیری

منسوخ شدن API بخشی اجتناب ناپذیر از خدمات نرم افزاری در حال تکامل است. با پیروی از بهترین شیوه‌ها – ارتباط واضح، ارائه گزینه‌های جایگزین و به‌روزرسانی اسناد – می‌توانید انتقال آرام را برای کاربران خود تضمین کنید. به یاد داشته باشید که از ابزارهایی مانند هدر HTTP Deprecation استفاده کنید و مشخصات OpenAPI خود را به روز کنید تا تغییرات را به طور دقیق منعکس کنید.

paths:
  /v1/old-endpoint:
    get:
      deprecated: true
      summary: "Deprecated endpoint for retrieving user data"
      description:
        "This endpoint is deprecated and will be removed on YYYY-MM-DD. Use
        /v2/new-endpoint instead."
      responses:
        "200":
          description: Successful response

openapi: 3.0.0
info:
  version: "1.0.0"
  title: "Deprecated API Version"
  description:
    "Version 1.0.0 is deprecated and will be retired on YYYY-MM-DD. Please
    upgrade to version 2.0.0."
  x-deprecation: "2023-11-11T23:59:59Z"
paths:
  /v1/endpoint:
    get:
      summary: "Endpoint in deprecated API version"
      responses:
        "200":
          description: Successful response

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        username:
          type: string
        fullName:
          type: string
          deprecated: true
          description:
            "This field is deprecated and will be removed on YYYY-MM-DD. Use
            'firstName' and 'lastName' instead."
        firstName:
          type: string
        lastName:
          type: string

Deprecation: @1688169599

const express = require("express");
const app = express();

app.get("/v1/old-endpoint", (req, res) => {
  const deprecationDate = new Date().now();
  res.set("Deprecation", deprecationDate);
  res.json({ message: "This endpoint is deprecated." });
});

app.listen(3000, () => console.log("Server running on port 3000"));

const fastify = require("fastify")();
fastify.register(require("fastify-swagger"), {
  exposeRoute: true,
  routePrefix: "/documentation",
  swagger: {
    info: {
      title: "API Documentation",
      version: "1.0.0",
    },
  },
});

fastify.get(
  "/v1/old-endpoint",
  {
    schema: {
      deprecated: true,
      summary: "Deprecated endpoint",
      description:
        "This endpoint is deprecated and will be removed in the future.",
      response: {
        200: {
          type: "object",
          properties: {
            message: { type: "string" },
          },
        },
      },
    },
  },
  async (request, reply) => {
    reply.header("Deprecation", "true");
    return { message: "This endpoint is deprecated." };
  },
);

fastify.listen(3000, (err) => {
  if (err) throw err;
  console.log("Server running on port 3000");
});

@RestController
public class UserController {

    @Deprecated
    @GetMapping("/v1/old-endpoint")
    public ResponseEntity<String> oldEndpoint() {
        return ResponseEntity.ok("This endpoint is deprecated.");
    }

    @GetMapping("/v2/new-endpoint")
    public ResponseEntity<String> newEndpoint() {
        return ResponseEntity.ok("This is the new endpoint.");
    }
}

[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
    [Obsolete("This endpoint is deprecated. Use GET /v2/some-endpoint instead.", false)]
    [HttpGet("v1/some-endpoint")]
    public IActionResult OldEndpoint()
    {
        return Ok("This endpoint is deprecated.");
    }

    [HttpGet("v2/some-endpoint")]
    public IActionResult NewEndpoint()
    {
        return Ok("This is the new endpoint.");
    }
}

from rest_framework.decorators import api_view
from rest_framework.response import Response
from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(method='get', deprecated=True)
@api_view(['GET'])
def old_endpoint(request):
    return Response({'message': 'This endpoint is deprecated.'})

plugins:
  - name: response-transformer
    config:
      add:
        headers:
          - "Deprecation: @1688169599"

 async="false" continueOnError="false" enabled="true" name="AddDeprecationHeader">
    
        
            
 name="Deprecation">@1688169599
        
    
    true