ساخت API مدرن با GraphQL، بخش اول

تا حالا شده وسط پیاده‌سازی کد، اعضای تیم مجبور بشن چندین بار از هم بپرسند که جزئیات رِست (Rest) ای‌پی‌آی چیه؟ و مجبور بشید برید وسط کدها بگردید تا پارامترهای ای‌پی‌آی رو پیدا کنید تا به هم‌تیمی‌تون بگید چجوری باید درخواست بده؟ یا اینکه کد ای‌پی‌آی عوض شده و هماهنگی‌ها به درستی انجام نشده و محصول به مشکل خورده؟ گرف‌کیوال می‌تونه بسیاری از این مشکلات رو کم کنه و به شما کمک کنه با اطمینان محصول توسعه پیدا کنه و تجربه‌ی توسعه (DX، Developer Experience) و حتی تجربه‌ی کاربری (UX) بهتری داشته باشید. در ادامه به بررسی گرف‌کیوال خواهیم پرداخت.

گرف‌کیوال چیست؟

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

چرا گرف‌کیوال؟

در ابتدا تعدادی از مشکلاتی که ای‌پی‌ای‌های رِست (Rest) داشتند رو توضیح می‌دم، بعدش می‌گم که گرف‌کیوال چجوری این مشکلات رو حل می‌کنه.

مشکل over-fetching

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

در گرف‌کیوال، کلاینت دقیقا می‌گه چه فیلدهایی رو نیاز داره و سرور تنها اون اطلاعت رو ارسال می‌کنه. مثلا در صفحه‌ی لیست کتاب‌ها فقط به عنوان نیاز دارید و در صفحه جزئیات کتاب، اکثر فیلدها رو درخواست می‌دید و در هر صفحه تنها به اندازی کافی دیتا دریافت می‌کنید.

مشکل under-fetching

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

در گرف‌کیوال، امکان کوئری زدن دیتا‌های مرتبط وجود داره، یعنی کلاینت می‌گه عنوان کتاب و نام نویسنده رو نیاز دارم و کل دیتا در یک درخواست به دست کلاینت می‌رسه:

مشکل حدس زدن و عدم اطمینان

فرض بگیرید یک ای‌پی‌آی رِستی وجود دارد که اطلاعات مربوط به پست‌ها و کامنت‌های یک بلاگ رو در اختیار شما قرار می‌ده. و شما قصد دارید لیست پست‌ها رو بگیرید، دقیقا باید به کجا درخواست بدید؟ احتمالا درخواست باید به ‎/api/posts زده بشه، اگه بخواید یه تک پست رو دریافت کنید چطور؟ ‎/posts/45 هستش یا ‎/post/45 و لیست کامنت‌های یک پست از کجا می‌آد؟ ‎/posts/45/comments و یا یه روش دیگه؟

الان یه پست چه مقادیری رو به من بر می‌گردونه؟ عنوان در چه فیلدی هستش؟ title یا post_title یا postTitle یا ... آیا متن پست در پاسخ سرور هستش یا صرفا خلاصه پست اومده؟ آیا تعداد کامنت رو هم می‌ده؟

اگه در آینده یکی از این فرضیات عوض بشه چی؟ چه زمانی و به چه طریقی قراره بفهمیم، آیا توسعه‌دهنده‌ی backend شخصا به توسعه‌دهندگان frontend باید خبر بده؟

البته برخی از این مشکلات با روش‌هایی مثل استفاده از swagger قابل حل هستند، ولی هم زحمت پیاده‌سازی‌اش وجود داره، و خیلی وقت‌ها هم واقعا کسی همت نکرده و کلا وجود نداره.

اما در گرف‌کیوال همه‌ی درخواست‌ها به یک end-point می‌ره، هم‌چنین از ابتدا مفهوم اسکیما (schema) وجود داشته که می‌گفته دقیقا چه تایپ‌هایی وجود داره، هر تایپ چه فیلد‌هایی داره و تایپ هر فیلد چیه و این امکان وجود داره که برای هر فیلد مستندات و توضیحاتی اضافه کنید. دیگه لازم نیست اسم فیلد‌ها حدس زده بشه.

حتی ابزارهای مختلفی وجود داره که در هنگام توسعه بر اساس اسکیما راهنمایی می‌کنند که چه فیلد‌هایی وجود داره. هم‌چنین می‌شه در زمان کامپایل و قبل از اجرای برنامه صحت کوئری‌ها بررسی بشه. و برای زبان‌هایی مثل typescript و یا kotlin که تایپ رو پشتیبانی می‌کنند، تایپ‌های متناظر با کوئری ساخته می‌شه و هنگام استفاده از پاسخ سرور با اطمینان کامل کد می‌زنیم.

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

جمع‌بندی

تا به اینجا گرف‌کیوال رو معرفی کردیم و برخی از فواید و مشکلاتی رو که حل می‌کنه رو بیان کردیم. در بخش بعد با استفاده از Django و Graphene یه ای‌پی‌آی ساده گرف‌کیوال رو پیاده سازی خواهیم کرد.