چند Best Practice در طراحی REST API

امروزه که همه چی به هم وصله، REST APIs با طراحی خوب، پایه و اساس برنامه‌های کاربردی کارآمد و قابل ارتقا هستن.

نوشتن دیزاین های REST API تمیز به چند دلیل خیلی مهمه:

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

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

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

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

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

مستندات بهتر: طراحی‌های تمیز، مستندسازی رو هم ساده‌تر می‌کنن و نحوه کارکرد API و نحوه استفاده درست ازش رو به طور کامل برای برنامه‌نویس‌ها توضیح می‌دن. اینجوری همه چی شفاف میشه و استفاده از API هم راحت‌تر میشه.


رولز ها یا قوانین URI

ساختار یه URI به شکل زیره:

scheme :// authority / path [?query][#fragment]

مثال:

https://soccer.api.org/teams/dortmund/players?name=Rona#2

تو دنیای URI دو نوع منبع (resource) داریم:

منابع مجموعه (Collection resources): این نوع منبع، مجموعه‌ای از منابع دیگه رو در خودش داره. میشه اون رو به یه جدول تو دیتابیس تشبیه کرد. مثلا میشه یه منبع مجموعه به اسم users داشته باشیم که لیستی از تمام کاربرها رو در خودش داره.

منابع تکی (Singleton resources): این نوع منبع، فقط شامل یه منبع واحده. میشه اون رو به یه رکورد تو دیتابیس تشبیه کرد. مثلا میشه یه منبع تکی به اسم users/123 داشته باشیم که اطلاعات مربوط به یه کاربر خاص با شناسه ۱‍۲‍۳ رو نشون بده

نکات مهم طراحی Rest Api

۱. منابع Collection باید جمع (plural) باشن :

✅ soccer.api.org/teams/dortmond
❌ soccer.api.org/team/dortmond

۲. منابع Singleton باید مفرد (singular) باشن و با شناسه یکتاشون (unique id) جایگزین بشن:

فرض کن میخوای اطلاعات یه بازیکن خاص رو نمایش بدی، بجای استفاده از players/Ronaldo بهتره از شناسه عددی یا کد اون بازیکن استفاده کنی، مثلا players/12345.

✅ soccer.api.org/teams/dortmond/players/58c1aaae-205a-11ef-aeea-a64c74618950

۳. اسلش ته آدرس رو حذف کنید:

✅ soccer.api.org/teams/dortmond/players
❌ soccer.api.org/teams/dortmond/players/

۴. برای بهتر خونده شدن، از خط تیره (-) به جای زیرخط (_) استفاده کنید:

✅ api.blog.com/blogs/this-is-my-blog
❌ api.blog.com/blogs/this_is_my_blog

۵. تو مسیرهای URI از حروف کوچک استفاده کنید:

✅ api.example.com/my-api/my-resource
❌ api.example.com/My-Api/My-Resource

۶. تو URI ها از پسوند فایل استفاده نکنید:

✅ api.example.com/api/resource
❌ api.example.com/api/resource.json

۷. از اسم فانکشن های CRUD تو URI استفاده نکنید:

برای عملیات ایجاد، خواندن، بروزرسانی و حذف منابع، از اسم هایی مثل create, read, update, delete تو URI استفاده نکن. بجاش از Http Method های استاندارد استفاده کن.
✅ DELETE api.example.com/api/resource
❌ GET api.example.com/api.resource/delete



✅ GET /users
❌ GET /getUsers

۸. بخش کوئری (query) تو URI فقط برای منابع Collection قابل استفاده است:

✅ GET /users?role=admin
❌ GET /users/admin

۹. از بخش کوئری برای اسکرول (paging) کردن نتایج منابع مجموعه استفاده کنید:

✅ GET /users?pageSize=25&pageStartIndex=50

نسخه بندی API (Versioning)

نسخه بندی API برای موارد زیر اهمیت داره:

حفظ سازگاری قبلی (Maintaining backward compatibility)

تضمین یک API سازگار و با طراحی خوب: استفاده از نام‌گذاری‌های یکسان تو همه نسخه‌ها به یه تجربه کاربری خوب کمک میکنه. تغییر endpoint این تجربه رو بهم میریزه و نسخه بندی به جلوگیری از این موضوع کمک میکنه.

چند استراتزی برای نسخه بندی API:

URI Versioning (پیشنهادی):

✅ GET /api/v1/users
✅ GET /api/v2/users

Header Versioning:

✅ GET /api/users
Headers: { "X-API-Version": "1" }

✅ GET /api/users
Headers: { "X-API-Version": "2" }


🆔 @MdDaily

در لاراول یه هلپر مفید داریم با نام literal که بهمون این امکان رو میده با استفاده از آرگومان های نامگذاری شده، یک آبجکت php بسازیم.

مزایاش ؟؟
افزایش خوانایی کد .
ساده تر شدن نحوه مدیریتشون .( مخصوصا در شرایطی که تعداد آرگومان ها زیاده مدیریت برامون ساده تر میشه با استفاده از هلپر literal ).

به مثالش در تصویر دقت کنین تا بهتر براتون جابیفته.
#Laravel
#لاراول
#برنامه_نویسی_وب
#برنامه_نویسی
@GoldenCodeir
(به منبع و مثالش دقت کنید👇🏾)
https://x.com/OussamaMater/status/1800258725078274249?s=19

در لاراول وقتی با کالکشن ها کار می‌کنیم اگر بخوایم اولین آیتمی که با شرط مورد نظرمون مطابقت داره رو بگیریم، میتونیم از متود ()sole استفاده کنیم.👌🏾

اگر هم بیشتر از یه آیتم با شرط مطابقت داشته باشه exception برمیگرده.
همچنین اگر هیچ آیتمی مطابق با شرط نباشه باز هم exception برمیگرده.

طرز کارش سادست،کافیه به تصویر دقت کنین ✔️
#Laravel
@GoldenCodeir
(به منبع و مثالش دقت کنید👇🏾)
https://x.com/OussamaMater/status/1800982923039912370?t=Xc2MWc7xLWTSTsRWfQWfDQ&s=35

یه نکته مهم❗️

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

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

@TheRaymondDev

لازم نیست برای چند زبانه کردن سایت دنبال تکنیک و ترفند باشید!

"ترجمه گوگل" بهترین گزینه برای چند زبانه کردن سایت هستش که برای شما دوستان Golden Code ای کدهاشو نوشتم.

- پشتیبانی همه زبان ها
- سرعت بالای ترجمه
- ظاهری زیبا
- استفاده آسان

تنها با چند کپی پیست ازش استفاده کنید و لذت ببرید ❤️

https://github.com/mordadam/google-translate-html-js

هنگام ساخت کاربر جدید در بیشتر مواقع برای رمز عبور از فسادِ Hash استفاده میکنیم اما روش دیگه ای هم لاراول در اختیارمون گذاشته .

میتونیم با کمک cast تعیین کنیم که attribute 'پسورد' بصورت هش شده ذخیره بشه. برای این کار کافیه از عبارت 'hashed' کمک بگیریم و نوع این attribute رو تعیین کنیم.
#laravel
#لاراول
@GoldenCodeir
(به منبع و مثالش دقت کنید👇🏾)
https://x.com/OussamaMater/status/1801356734063399150?s=35

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

متود ()logoutOtherDevices بهمون اجازه میده تا همه session های کاربر روی دستگاه های دیگه رو غیرفعال کنیم و فقط session فعلی باقی بمونه.

طرز کارش هم اینجوریه که پسورد فعلیش رو باید به عنوان پارامتر پاس بدیم به این متود تا اعتبار سنجی انجام بشه.🪴
#laravel
#لاراول
@GoldenCodeir
(به منبع و مثالش توجه کنید👇🏾)
https://x.com/OussamaMater/status/1803533220362985736?s=19

-اصل Use Pronounceable Names در کلین کد

این اصل میگه که شما باید اسم هایی که برای متغیر هاتون انتخاب میکنید قابل تلفظ باشه اگه نتونید تلفظش کنید نمیتونید در بارش بحث کنید بدون این که صدای احمقانه در بیارید این مهمه چون برنامه نویسی یه فعالیت اجتماعیه

ما برنامه نویسا باید اسم هارو جوری انتخاب کنیم که وقتی در بارش توضیح میدیم راحت باشیم مثلا این دوتا کد رو ببینید اولی اسم های غیر قابل تلفظ داره و دومی اسم های درست درمون

کد زیر :

class DtaRcd102 {
      private Date genymdhms;
      private Date modymdhms;
      private final String pszqint = "102";
};

میتونه با متغیر های بهتر زیر نوشته باشه :

class Customer {
      private Date generationTimestamp;
      private Date modificationTimestamp;
      private final String recordId = "102";
};

حالا وقتی میخوایم به رفیقمون بگیم بیا یه نگاه به این کد بنداز دیگه راحت تلفظ میکنیم و صدای احمقانه در نمیاریم


#CleanCode
@CleverDevs
@CleverDevsGp

از نسخه ۹ به بعد لاراول، میتونیم برای انجام عملیات ریدایرکت کاربر به مسیر مدنظر، بجای ()redirect()->route از هلپر ()to_route استفاده کنیم .

استفاده ازین هلپر باعث کوتاه تر شدن و تمیز تر شدن کدمون خواهد شد. ✔️
#لاراول
#Laravel
@GoldenCodeir
(به منبع و مثالش دقت کنید👇🏾)
https://x.com/PovilasKorop/status/1805175287686078690?s=19

🔶 تفاوت متد boot و register توی Provider ها چیست؟

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

اما به محض اینکه متد register همه‌ی پرووایدرها پردازش شد، متد boot همه پرووایدرها توسط فریم‌ورک شروع به پردازش شدن می‌کنه. این رو می‌تونین با یک echo ساده بررسی‌ کنین. پس توی متد boot ما مطمئن هستیم که همه‌ی پرووایدرها رجیستر شدن. پس کارهایی غیر از bind کردن مثل استفاده از یک پرووایدر دیگه، اضافه کردن فایل‌های Route، ثبت کردن Event/Listerner ها و ... رو توی متد boot می‌نویسیم.

</ Farshad Rajabzade >

#لاراول

@TheRaymondDev

"در لاراول جهت مرتب سازی مدل بر اساس تاریخ، اغلب از متود ()orderBy استفاده میشه.

اما فریمورک لاراول با ارائه دو متود ()latest و ()oldest این فرایند رو برای ما خوانا تر و کوتاه تر کرده.👌🏾

(به مثال سه توجه کنین،تفاوته فرایند مرتب سازی با این دو متود نسبت به orderBy کاملن شفافه).

نکته: مرتب سازی بطور پیشفرض ستون create_at هست که قابل تغییره"
#Laravel
@GoldenCodeir
(به منبع و مثالش دقت کنید👇🏾)
https://x.com/OussamaMater/status/1804611139516453170?s=35

-اصل Avoid Encoding در کلین کد


این اصل میگه که ما به حد کافی رمزگذاری برای اسامی داریم که دیگه نخوایم رمزگذاری های بیشتری اضافه کنیم تا مسئولیتمون رو سخت تر کنیم
رمز گذاری کردن اطلاعات تایپ و اسکوپ ها توی اسامی به راحتی کار مارو سخت میکنه

کاری میکنه که هر کس جدیدی تو تیممون عضو بشه مجبوره بشینه و یادبگیره که این رمزا چین و ...

اسم هایی که رمزگذاری شدن به ندرت قابل تلفظ هستن و این خودش اصل قبلی رو نقض میکنه


#CleanCode
@CleverDevs
@CleverDevsGp

اره php مرده، دوبار
https://w3techs.com/technologies/overview/programming_language


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

@DevTwitter

-اصل Bad Comments در کلین کد

این دسته که از کامنت ها که بیشتر کامنت هایی که میزاریم رو شامل میشه کامنت هایی ان که سود خاصی برامون ندارن و الکی کد رو شلوغ میکنن
این اصل چنتا زیر مجموعه داره و کامنت های بدی که میتونید بزارید رو گفته تو این پست سعی میکنم به طور خلاصه همشون رو بگم

‏1 - Mumbling
یعنی اینکه کامنتی بزاری که نامفهمومه و بیشتر از اینکه بدرد بخور باشه باعث سر در گمیه

‏2 - Redundant Comments
یعنی کامنت هایی که بدرد نخور و اضافن و خوندوشون از خوندن کد کد زمان بیشتری میبره

‏3 - Misleading Comments
یعنی یجور لقمه رو دور سر بپیچونی که کسی که کامنت رو میخونه کلا فکر و ذهنش منحرف بشه به یه سمت دیگه

‏4 - Mandated Comments
کامنت هایی که برای هر متغیری مینویسد و معمولا زیاد بدرد نمیخورن مثل javadocs

‏5 - Journal Comments
اینکه بیای و تغییرات پروژه رو هر بار تو کامنتا بزنی ، اینکار برا قبل اومدن سیستم های کنترل ورژن مثل گیت بود این نوع کامنتا الان بدرد نمیخورن

‏6 - Noise Comments
کامنت هایی که کار خاصی ندارن و فقط کد رو شلوغ کردن مثل

/** The day of the month. */

private int dayOfMonth;

‏7 - Commented-Out Code
کامنت کردن کد ها هم یکی از بدترین نوع کامنت هاست

‏8 - Too Much Information
یعنی اینکه تو کامنت اطلاعات زیادی بدی انقدر زیاد باشه خوندنش کلی وقت ببره

این فصل هم تموم شد و میتونید لیستش رو اینجا ببینید

#CleanCode
@CleverDevs - @CleverDevsGp

#Typenoscript
✅ تایپ اسکریپت:
بر روی زبان جاوا اسکریپت بنا شده است و سیستم تایپ را به آن اضافه می کند.
کامپایل می شود و قبل از اجرا به جاوا اسکریپت تبدیل می شود.
✅ مزایا:
سیستم تایپ: به شما کمک می کند تا از خطاهای زمان اجرا جلوگیری کنید.
خوانایی بهتر: کدهای تایپ اسکریپت به دلیل سیستم تایپ، خوانایی بهتری دارند.
قابلیت نگهداری: به دلیل سیستم تایپ، نگهداری و توسعه کدهای تایپ اسکریپت آسان تر است.
✅ معایب:
یادگیری دشوارتر: به دلیل وجود سیستم تایپ، یادگیری آن کمی دشوارتر از جاوا اسکریپت است.
سرعت: به دلیل کامپایل شدن، سرعت اجرای آن کمی کندتر از جاوا اسکریپت است.
جامعه کوچکتر: به دلیل جدیدتر بودن، جامعه آن به اندازه جاوا اسکریپت بزرگ نیست.
💥 انتخاب بین جاوا اسکریپت و تایپ اسکریپت: 💥

✅ انتخاب بین این دو زبان به نیازهای شما بستگی دارد. اگر به دنبال یک زبان برنامه نویسی آسان برای یادگیری هستید و سرعت برای شما مهم است، جاوا اسکریپت گزینه مناسبی است. اما اگر به دنبال یک زبان برنامه نویسی با سیستم تایپ قوی و خوانایی بالا هستید، تایپ اسکریپت گزینه بهتری است.
Channel | Group | YouTube