استفاده از مشخصات Json API برای طراحی و توسعه API های RESTful

Summarize this content to 400 words in Persian Lang

REST API چیست؟

REST API یک API است که مطابق با سبک معماری انتقال وضعیت نمایندگی است. یک API به ما می گوید که چگونه می توانیم با هر سرویس یا سیستمی ارتباط برقرار کنیم و چه عملیاتی را می توانیم روی آن انجام دهیم.

معمولاً API های REST بر روی پروتکل HTTP توسعه یافته و در معرض دید قرار می گیرند. به عنوان HTTP خود، به افعال HTTP مانند GET، POST، PUT، DELETE و غیره پاسخ می دهد که ذاتاً عملیاتی است که می توانیم با استفاده از API ها انجام دهیم.

API های REST معمولاً برای برقراری ارتباط بین دو سیستم یا برنامه در هر پلتفرمی که از پروتکل HTTP پشتیبانی می کند مانند رایانه ها، تلفن ها، تبلت ها، دستگاه های IoT و بسیاری موارد دیگر استفاده می شود.

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

متأسفانه، (اگرچه با زبان های برنامه نویسی مدرن مانند .NET core، جاوا یا NodeJS و غیره که نوشتن یک سرویس API را تقریباً در عرض چند دقیقه آسان می کند…) توسعه یک سرویس API کارآمد، مقیاس پذیر، بهینه و به طور کلی دشوار است. همه یا اکثر جعبه‌هایی برای کیفیت که در سرویس API به دنبال آن هستیم.

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

مشخصات JSON API چیست؟

JSON API مشخصه ای است برای اینکه چگونه یک کلاینت باید درخواست کند که منابع واکشی یا اصلاح شوند و چگونه سرور باید به این درخواست ها پاسخ دهد.

اینها مجموعه قوانینی هستند که برای طراحی REST APIها مشخص شده اند که در صورت انطباق با آنها، می تواند REST API شما را به یک API سازگار با JSON تبدیل کند. همانطور که قبلاً در سایت رسمی توضیح داده شده است، در اینجا وارد مشخصات کامل نمی شوم.

وقتی می دانیم چگونه API های REST بنویسیم، چرا به یک مشخصات نیاز داریم

از آنجایی که API های REST تقریباً بیش از 2 دهه است که وجود دارند، ممکن است تعجب کنیم که چرا واقعاً برای نوشتن یک REST API باید از یک مشخصات پیروی کنیم.

خوب، تا زمانی که با یک یا چند موقعیت در سرویس API خود برخورد نکنید، این کار را نمی کنید:

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

_

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

چگونه API های Json می توانند به طراحی API های REST مقیاس پذیر و قابل نگهداری کمک کنند

مشخصات JSON API مجموعه ای از قوانین را به تفصیل شرح می دهد، اما من می خواهم چند ویژگی را که تقریباً در هر API بسیار مورد نیاز است و اینکه چگونه مشخصات JSON API در این موارد کمک می کند را لیست کنم:

مذاکره محتوا

مسئولیت‌های مشتری و سرور یا هر دو را برای مذاکره درباره محتوای درخواستی/بازگرداندن مشخص می‌کند.

کلاینت ها و سرورها باید همه بارهای JSON:API را با استفاده از نوع رسانه JSON:API در هدر Content-Type ارسال کنند.

کلاینت ها و سرورها باید پارامتر نوع رسانه ext را در هدر Content-Type مشخص کنند که یک یا چند پسوند را برای یک سند JSON:API اعمال کرده اند.

وقتی یک یا چند نمایه را روی یک سند JSON:API اعمال می‌کنند، کلاینت‌ها و سرورها باید پارامترهای نوع رسانه نمایه را در هدر Content-Type مشخص کنند.

طرح و ساختار یکنواخت سند

یک شی JSON باید در ریشه هر درخواست JSON:API و سند پاسخ حاوی داده باشد. این شی “سطح بالای” یک سند را تعریف می کند.

یک سند باید حداقل یکی از اعضای سطح بالای زیر را شامل شود:داده: “داده های اولیه” سند.

errors: آرایه ای از اشیاء خطا.

متا: یک متا شی که حاوی متا اطلاعات غیر استاندارد است.عضوی که توسط یک پسوند اعمال شده تعریف شده است.داده های اعضا و خطاها نباید در یک سند وجود داشته باشند.یک سند ممکن است حاوی هر یک از این اعضای سطح بالا باشد:

jsonapi: یک شی که پیاده سازی سرور را توصیف می کند.

پیوندها: یک شی پیوند مربوط به داده های اولیه.

شامل: آرایه ای از اشیاء منبع که به داده های اولیه و/یا یکدیگر مرتبط هستند (“منابع شامل”).

مدیریت داده‌های والدین/فرزند یا داده‌های مرتبط (و اینکه آیا در پاسخ باید آن‌ها را بازگردانید)

برای درک اینکه چگونه مشخصات Json API توصیف اطلاعات منابع والدین و فرزند را تجویز می کند، ابتدا باید ساختار سند سند Json API را همانطور که در پیوند زیر توضیح داده شده است، درک کنیم:

ساختار سند

هنگام توصیف منابع مرتبط از روابط ویژگی استفاده می شود.

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

منبع نمونه با اطلاعات منابع مرتبط و طرح ویژگی پیوند:

// …
{
“type”: “articles”,
“id”: “1”,
“attributes”: {
“title”: “Rails is Omakase”
},
“relationships”: {
“author”: {
“links”: {
“self”: “http://example.com/articles/1/relationships/author”,
“related”: “http://example.com/articles/1/author”
},
“data”: { “type”: “people”, “id”: “9” }
}
},
“links”: {
“self”: “http://example.com/articles/1”
}
}
// …

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

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

برای مدیریت اسناد پیچیده مرتبط، می توانیم از مشخصات اسناد مرکب همانطور که در لینک زیر توضیح داده شده است استفاده کنیم

اسناد مرکب

صفحه بندی

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

پارامتر صفحه پرس و جو برای صفحه بندی رزرو شده است. سرورها و مشتریان باید از این پارامترها برای عملیات صفحه بندی استفاده کنید.

/?page[offset]=0&page[limit]=10

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

اول: صفحه اول داده ها
last: آخرین صفحه داده ها
prev: صفحه قبلی داده ها
بعدی: صفحه بعدی داده ها

فیلتر کردن / مرتب سازی

یک نقطه پایانی ممکن است از پارامتر پرس و جو مرتب‌سازی در درخواست خود پشتیبانی کند و یک یا چند مقدار پارامتر را با کاما جدا شده بپذیرد.

GET /people?sort=age,name HTTP/1.1

مجموعه های میدان پراکنده

یک مشتری ممکن است یک نقطه پایانی را درخواست کند تا در پاسخ فقط فیلدهای خاصی را برگرداند. این به ویژه زمانی مفید است که ما از نقاط پایانی API استفاده می کنیم که بسیاری از فیلدها را در پاسخ برمی گرداند و ما فقط به چند مورد علاقه مند هستیم. مشخصات Json API به تعیین تنها فیلدهایی که می خواهیم در پاسخ ببینیم کمک می کند.

به عنوان مثال،

GET /articles?include=author&fields[articles]=title,body&fields[people]=name HTTP/1.1 Accept: application/vnd.api+json

رسیدگی به خطا

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

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

هنگامی که یک سرور برای یک درخواست واحد با مشکلات متعددی مواجه می‌شود، عموماً کاربردی‌ترین کد خطای HTTP باید در پاسخ استفاده شود. به عنوان مثال، 400 Bad Request ممکن است برای چندین خطای 4xx یا 500 Internal Server Error برای چندین خطای 5xx مناسب باشد.

اشیاء خطا اطلاعات بیشتری در مورد مشکلاتی که در حین انجام یک عملیات با آن مواجه می شوند ارائه می دهند. اشیاء خطا باید به‌عنوان آرایه‌ای که با خطاهای سطح بالای یک سند JSON:API کلید می‌خورد، بازگردانده شوند.

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

id: یک شناسه منحصر به فرد برای این رخداد خاص از مشکل.

پیوندها: یک شی پیوند که ممکن است حاوی اعضای زیر باشد:

about: پیوندی که به جزئیات بیشتر در مورد این اتفاق خاص از مشکل منجر می شود. در هنگام ارجاع، این URI باید یک توصیف قابل خواندن توسط انسان از خطا را برگرداند.

type: پیوندی که نوع خطایی را که این خطای خاص نمونه ای از آن است، مشخص می کند. این URI باید قابل ارجاع به یک توضیح قابل خواندن توسط انسان از خطای عمومی باشد.

status: کد وضعیت HTTP قابل اعمال برای این مشکل، که به صورت یک مقدار رشته بیان می شود. این باید ارائه شود.

کد: یک کد خطای خاص برنامه، که به عنوان یک مقدار رشته بیان می شود.

عنوان: خلاصه ای کوتاه و قابل خواندن برای انسان از مشکلی که نباید از یک وقوع به وقوع مشکل تغییر کند، مگر برای اهداف محلی سازی.

جزئیات: توضیحی قابل خواندن برای انسان مخصوص این رخداد مشکل. مانند عنوان، مقدار این فیلد را می توان بومی سازی کرد.

منبع: یک شی حاوی ارجاع به منبع اصلی خطا. باید شامل یکی از اعضای زیر باشد یا حذف شود:

اشاره گر: یک اشاره گر JSON [RFC6901] به مقدار موجود در سند درخواست که باعث خطا شده است [e.g. “/data” for a primary data object, or “/data/attributes/title” for a specific attribute]. این باید به یک مقدار در سند درخواستی که وجود دارد اشاره کند. اگر اینطور نیست، مشتری باید به سادگی نشانگر را نادیده بگیرد.

پارامتر: رشته ای که نشان می دهد کدام پارامتر کوئری URI باعث خطا شده است.

header: رشته ای که نام یک هدر درخواست را نشان می دهد که باعث ایجاد خطا شده است.

متا: یک متا شی حاوی متا اطلاعات غیر استاندارد در مورد خطا.

توسعه JSON API و مصرف از طریق برنامه مشتری

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

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

در زیر کتابخانه های موجود بر اساس زبان برنامه نویسی آمده است:

کتابخانه های سرور

کتابخانه های مشتری

مرجع

JSON:API — آخرین مشخصات (نسخه 1.1) (jsonapi.org)

از medium.com منتقل شد

// ...
{
  "type": "articles",
  "id": "1",
  "attributes": {
    "title": "Rails is Omakase"
  },
  "relationships": {
    "author": {
      "links": {
        "self": "http://example.com/articles/1/relationships/author",
        "related": "http://example.com/articles/1/author"
      },
      "data": { "type": "people", "id": "9" }
    }
  },
  "links": {
    "self": "http://example.com/articles/1"
  }
}
// ...