📕 کتاب REST API Design Rulebook

📌 فصل سوم: Interaction Design with HTTP

📍پارت: اول

#کتاب

√

Dune: a shell from a bored student working on projects to fill the time.

Home Page

GitHub

#tool #shell

گنوم ۴۷ منتشر شد.


https://release.gnome.org/47


@SohrabContents

نکات کلیدی:
- بعد از پردازش موفقیت‌آمیز درخواست DELETE`، منبع دیگه توسط کلاینت‌ها قابل دسترسی نخواهد بود. یعنی اگر بعداً کلاینت‌ها با استفاده از متدهای `GET یا HEAD سعی کنند وضعیت اون منبع رو بگیرند، باید پاسخ 404 (Not Found) برگرده.
- DELETE در HTTP معنای خاصی داره و نباید توسط طراحی API تغییر داده یا بیش از حد بسط داده بشه. اگر API نیاز به یک حذف "نرم" (soft delete) یا یک تعامل دیگه داره که فقط حالت منبع رو تغییر می‌ده ولی اون رو کاملاً حذف نمی‌کنه، بهتره از یک کنترلر ویژه با متد POST استفاده کنه، نه DELETE.

مثال:
فرض کنید یک کلاینت می‌خواد یک سند رو از یک فروشگاه حذف کنه:

DELETE /accounts/4ef2d5d0-cb7e-11e0-9572-0800200c9a66/buckets/objects/4321

توضیح:
- در اینجا درخواست DELETE برای حذف کامل شیء (document) با شناسه 4321 از داخل یک سطل (bucket) مشخص در حساب کاربری ارسال شده.

پس از موفقیت‌آمیز بودن درخواست، منبع کاملاً حذف می‌شه و هر تلاشی برای دسترسی به اون منبع با پاسخ "Not Found" مواجه می‌شه.

⭕️ متد OPTIONS باید برای دریافت متادیتایی استفاده بشه که تعاملات قابل دسترسی یک منبع رو توضیح می‌ده. کلاینت‌ها می‌تونن از درخواست OPTIONS استفاده کنن تا بفهمند چه متدهایی برای یک منبع در دسترس هستند.

نکات کلیدی:
- پاسخ به درخواست OPTIONS معمولاً شامل هدر Allow است که لیستی از متدهای HTTP قابل اجرا روی منبع رو نشان می‌ده. برای مثال:

    Allow: GET, PUT, DELETE
    

- علاوه بر این، یک API ممکنه در بدنه پاسخ (response body) جزئیات بیشتری درباره هر گزینه تعامل فراهم کنه. این جزئیات می‌تونن شامل فهرستی از فرم‌های ارتباط (link relation forms) باشند که نحوه تعامل با منبع رو نشان می‌دهند.

مثال:
فرض کنید یک کلاینت می‌خواد بفهمه که چه متدهایی روی یک منبع خاص در دسترس هستند:

OPTIONS /accounts/4ef2d5d0-cb7e-11e0-9572-0800200c9a66/buckets/objects/4321

پاسخ:
API ممکنه هدر Allow رو برگردونه که نشون می‌ده کدوم متدها روی منبع مورد نظر قابل استفاده هستند. برای مثال:

Allow: GET, PUT, DELETE

این متد به کلاینت اجازه می‌ده قبل از انجام عملیات، درباره تعاملات ممکن با یک منبع اطلاعات بیشتری کسب کنه.

@ninja_learn_ir

HTTP/1.1 200 OK
Date: Wed, 18 Sep 2024 10:00:00 GMT
Content-Type: text/html; charset=UTF-8
Content-Length: 1234
Connection: keep-alive
Server: Apache/2.4.29 (Ubuntu)

این متد برای وقتی خوبه که بخوایم چک کنیم یه منبع هست یا نه، یا اینکه اطلاعات کلی مثل حجم محتوا و نوع سرور رو ببینیم.



⭕️ متد PUT باید هم برای اضافه کردن و هم برای به‌روزرسانی یک منبع ذخیره شده استفاده بشه. این یعنی:
- اضافه کردن یک منبع جدید: وقتی می‌خواهیم یک منبع جدید اضافه کنیم، URL یا URI (آدرس منبع) توسط کلاینت مشخص میشه.
- به‌روزرسانی یا جایگزینی منبع موجود: برای به‌روزرسانی یا جایگزینی یک منبعی که از قبل ذخیره شده هم از PUT استفاده می‌کنیم.

مثال:
فرض کنید یه API داریم که یه فروشگاه منابع رو برای کلاینت‌هاش فراهم می‌کنه تا داده‌هاشون رو به‌صورت آبجکت ذخیره کنن. درخواست PUT به این صورت می‌تونه باشه:

PUT /accounts/4ef2d5d0-cb7e-11e0-9572-0800200c9a66/buckets/objects/4321

درخواست PUT:
در پیام درخواست PUT، باید نمایشی از منبعی که کلاینت می‌خواد ذخیره کنه وجود داشته باشه. ولی محتوای درخواست ممکنه دقیقاً همونی نباشه که بعداً از طریق `GET دریافت میشه. برای مثال، ممکنه API اجازه بده که کلاینت فقط بخش‌های قابل تغییر (mutable) منبع رو بفرسته.

پشتیبانی از درخواست‌های شرطی (Conditional PUT):
در بخش بعدی ("قانون: فروشگاه‌ها باید از درخواست‌های شرطی PUT پشتیبانی کنند") توضیح داده شده که چطور یه API باید از هدرهای HTTP استفاده کنه تا PUT رو برای هم اضافه کردن و هم به‌روزرسانی منابع استفاده کنه.


⭕️ متد PUT باید برای به‌روزرسانی منابع قابل تغییر استفاده بشه. یعنی وقتی یک کلاینت می‌خواد تغییراتی روی یک منبع اعمال کنه، باید از PUT استفاده کنه.
درخواست PUT باید شامل یک بدنه (body) باشه که تغییرات مورد نظر رو نشون میده. این بدنه، وضعیت جدید منبع رو مشخص می‌کنه و وقتی که درخواست پردازش بشه، منبع با این داده‌های جدید جایگزین میشه.


⭕️ از متد POST باید برای ایجاد یک منبع جدید در یک مجموعه (collection) استفاده بشه. یعنی وقتی کلاینت می‌خواد یک منبع جدید به یک مجموعه اضافه کنه، از POST استفاده می‌کنه.
بدنه (body) درخواست POST شامل یک نمایش از وضعیت پیشنهادی منبع جدیدیه که قراره به مجموعه‌ای که توسط سرور مدیریت میشه، اضافه بشه.

مثال:
فرض کنید کلاینت می‌خواد یک بازیکن جدید به یک تیم اضافه کنه:

POST /leagues/seattle/teams/trebuchet/players

توضیح:
- در اینجا درخواست POST برای اضافه کردن یک بازیکن جدید به مجموعه بازیکنان تیم "trebuchet" در لیگ "seattle" است.
- بدنه درخواست ممکنه شامل اطلاعاتی باشه که حالت اولیه بازیکن جدید رو نشون میده، مثلاً نام، سن و مشخصات دیگه.
این استفاده از POST شبیه اینه که یک پیام جدید روی یک تابلوی اعلانات قرار بدیم، یعنی یک آیتم جدید به یک مجموعه اضافه می‌کنیم.


⭕️ از متد POST برای اجرای کنترلرهای تابع‌محور (function-oriented controller resources) استفاده می‌شه. یعنی کلاینت‌ها زمانی از POST استفاده می‌کنند که بخواهند یک عملکرد یا عملیاتی رو فراخوانی کنند. پیام درخواست POST می‌تونه شامل هم هدر و هم بدنه (body) باشه که ورودی‌های لازم برای عملکرد کنترلر رو ارائه می‌ده.

نکات مهم:
- POST به صورت مفهومی "نامحدود" در نظر گرفته شده، به این معنی که این متد می‌تونه هر کاری انجام بده، صرف‌نظر از تکرارپذیری (idempotency) یا عواقب آن. به همین دلیل، POST انتخاب مناسبی برای کنترلرهای تابع‌محور هست که کارکرد مشخصی ندارند.
- از POST نباید برای گرفتن، ذخیره‌سازی یا حذف منابع استفاده بشه، چون HTTP برای هر کدام از این عملیات متدهای خاص خودش رو داره (مثل GET`، `PUT و DELETE).
‏- POST یک متد "unsafe" (ناامن) و "non-idempotent" (غیرتکرارپذیر) در نظر گرفته می‌شه. به این معنا که نتایجش غیرقابل پیش‌بینی و ممکنه تکرارش عواقب ناخواسته‌ای داشته باشه. مثلاً اگر یک فرم وب که از POST استفاده می‌کنه دوباره ارسال بشه، ممکنه باعث شارژ مضاعف کارت اعتباری کاربر بشه.

مثال:
فرض کنید کلاینت می‌خواد یک هشدار را مجدداً ارسال کنه:

POST /alerts/245743/resend

توضیح:
- در اینجا درخواست POST به کنترلر resend مربوط به هشدار مشخص شده (با آی‌دی 245743) ارسال شده تا عملیات ارسال مجدد انجام بشه.

این نوع استفاده از POST شبیه به مکانیزم "PostMessage" در سیستم‌های اجرایی (runtime) هست که به کلاینت اجازه می‌ده عملکردهایی رو از طریق یک مرز (مثل شبکه یا یک سرویس) فراخوانی کنه.


⭕️ متد DELETE باید برای حذف کامل یک منبع از والد خودش (که معمولاً یک مجموعه یا فروشگاه است) استفاده بشه. وقتی یک کلاینت درخواست DELETE می‌فرسته، هدف اینه که منبع مورد نظر به‌طور کامل حذف بشه.

@ninja_learn_ir

📕 کتاب REST API Design Rulebook

📌 فصل سوم: Interaction Design with HTTP

📍پارت: اول

#کتاب

‏💎 HTTP/1.1 💎
‏APIهای REST همه جنبه‌های پروتکل HTTP نسخه ۱.۱ رو شامل می‌شن، مثل متد های درخواست، کدهای ریسپانس و هدرها. این کتاب HTTP رو به دو فصل تقسیم کرده؛ این فصل درباره متد های درخواست و استاتوس کدهای ریسپانس صحبت می‌کنه.

فصل ۴ هم درباره گنجاندن متا داده‌ها در طراحی API REST و هدرهای درخواست و پاسخ HTTP صحبت می‌کنه.

‏💎 Request Methods 💎‏
کلاینت‌ها متد تعامل مورد نظر رو در قسمت Request-Line یک درخواست HTTP مشخص می‌کنن. استاندارد RFC 2616 نحوه نوشتن Request-Line رو این‌طوری تعریف کرده:

Request-Line = Method SP Request-URI SP HTTP-Version CRLF

هر متد HTTP معنای مشخص و خاصی در زمینه منابع REST API داره. هدف GET اینه که نمایی از وضعیت یک منبع رو بگیره. HEAD برای دریافت متا داده‌های مربوط به وضعیت منبع استفاده می‌شه. PUT باید برای به‌روزرسانی یک منبع استفاده بشه. DELETE هم برای حذف یک منبع از والدش به کار می‌ره. POST هم برای ایجاد یک منبع جدید در یک مجموعه و اجرای کنترلرها استفاده می‌شه.

‏⭕️ GET و POST نباید برای تونل‌کردن سایر متد های درخواست استفاده بشن.
تونلینگ به هر نوع سوءاستفاده از HTTP گفته می‌شه که هدف یک پیام رو پنهان یا به اشتباه نمایش می‌ده و شفافیت پروتکل رو تضعیف می‌کنه.
یک API REST نباید طراحی خودشو با سوءاستفاده از متد های درخواست HTTP برای سازگاری با کلاینت‌هایی که دانش محدودی از HTTP دارن، به خطر بندازه. همیشه باید از متد های HTTP به‌طور صحیح و طبق قواعد این بخش استفاده کنی.


‏⭕️ GET باید برای دریافت نمایی از وضعیت یک منبع استفاده بشه.
یک کلاینت REST API از متد GET در درخواستش استفاده می‌کنه تا وضعیت یک منبع رو در یک فرم نمایشی دریافت کنه. پیام درخواست GET می‌تونه شامل هدرها باشه ولی body نداره.

معماری وب به شدت به ماهیت متد GET وابسته‌است. کلاینت‌ها باید بتونن درخواست‌های GET رو تکرار کنن بدون اینکه عوارض جانبی ایجاد بشه. کش‌ها هم به این قابلیت اتکا دارن که بتونن نمایه‌های کش‌شده رو بدون تماس با سرور اصلی ارائه بدن.

در مثال زیر، می‌بینیم که چطور یک توسعه‌دهنده کلاینت ممکنه از curl در یک ترمینال برای دریافت نمایی از وضعیت فعلی یک منبع "greeting" استفاده کنه:

1️⃣ curl -v https://api.example.restapi.org/greeting

2️⃣ > GET /greeting HTTP/1.1
3️⃣ > User-Agent: curl/7.20.1
> Host: api.example.restapi.org
> Accept: */*
4️⃣ < HTTP/1.1 200 OK
5️⃣ < Date: Sat, 20 Aug 2011 16:02:40 GMT
< Server: Apache
< Expires: Sat, 20 Aug 2011 16:03:40 GMT
< Cache-Control: max-age=60, must-revalidate
< ETag: text/html:hello world
< Content-Length: 130
< Last-Modified: Sat, 20 Aug 2011 16:02:17 GMT
< Vary: Accept-Encoding
< Content-Type: text/html

6️⃣ <!doctype html><head><meta charset="utf-8"><title>Greeting</title></head>
<body><div id="greeting">Hello World!</div></body></html>

1️⃣ در اینجا، GET متد پیش‌فرض curl هست، بنابراین نیاز نیست به‌طور صریح مشخص بشه. گزینه -v هم باعث می‌شه خروجی curl جزئیات بیشتری داشته باشه.

2️⃣ خط Request-Line در درخواست نشون می‌ده که از متد GET برای منبع greeting استفاده شده.

3️⃣ لیست هدرهای پیام درخواست هم از اینجا شروع می‌شه. هدرهای درخواست و پاسخ HTTP در فصل ۴ توضیح داده شدن.

4️⃣ پیام پاسخ هم از اینجا شروع می‌شه، با خط وضعیت که در بخش "کدهای وضعیت پاسخ" در صفحه ۲۸ بحث شده. کد وضعیت ۲۰۰ OK به curl می‌گه که درخواستش موفقیت‌آمیز بوده.

5️⃣ لیست هدرهای پیام پاسخ هم از اینجا شروع می‌شه.

6️⃣ بدنه پیام ریسپانس هم از اینجا آغاز می‌شه. در این مثال، بدنه شامل یک نمای HTML از پیام خوشامدگویی هست.


⭕️ برای اینکه فقط هدرهای ریسپانس رو بگیریم بدون اینکه body دریافت کنیم، می‌تونیم از متد HEAD استفاده کنیم.
یعنی HEAD همون جواب GET رو میده، ولی بدون بدنه. از این روش میشه برای این استفاده کرد که ببینیم یه منبع وجود داره یا اینکه اطلاعات متادیتاش رو بخونیم.

مثال زیر یه دستور curl رو نشون میده که با استفاده از متد HEAD فقط هدرهای پاسخ رو می‌گیره:

curl -I https://example.com/resource

توضیح:
- -I یا --head: این گزینه به curl میگه که به جای درخواست معمولی GET`، یه درخواست `HEAD بفرسته.
- https://example.com/resource: آدرس منبعی که می‌خوایم چک کنیم رو باید اینجا بذاریم.

نتیجه مورد انتظار:
این دستور فقط هدرهای HTTP رو برمی‌گردونه و body در کار نیست. از این طریق می‌تونیم اطلاعاتی مثل کد وضعیت، نوع محتوا، جزئیات سرور و... رو ببینیم. مثلا خروجی می‌تونه این شکلی باشه:

@ninja_learn_ir

🐧 Gnu/Linux World News, Introduction  & Tutorials

https://t.iss.one/linuxiha

Join Us: @linuxiha

این meme رو دیدم خیلی جالب بود… عمق دانشنتون از PostgreSQL تا چه حدیه؟ یکم حس بی سوادی دست داد بهم :)) تو یکی از پستا چند روز پیش راجب یکیش پرداخته بودم 😁

Every sql operator is actually a join? WTF?😂

@ManiFoldsPython

دوستانی که کتاب دیگه مد نظرشون هست کامنت بذارن بعد اینکه این کتابو تموم کردیم کتابی که بیشترین رای رو آورد میذاریم 🌹

یک مقاله خیلی خوب برای توضیح دادن این میم:
https://avestura.dev/blog/explaining-the-postgres-meme

@PyBackendHub

🔶 نسخه ۴۷ گنوم به نام Denver به صورت رسمی منتشر شد.

https://release.gnome.org/47/

#لینوکس

@TheRaymondDev

🔶 دیسکورد بالاخره با افزودن رمزگذاری سرتاسری، قابلیت تماس ویدیویی و صوتی را امن‌تر کرد

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

#خبر

@TheRaymondDev

بتای فدورای ۴۱ اومده، اومدن ptyxis رو کردن ترمینال پیشفرض توی گنوم.


https://9to5linux.com/fedora-linux-41-enters-public-beta-testing-with-linux-kernel-6-11-and-gnome-47


ما همینکارو کردیم، دوستان کاربر گنوم می‌خواستن خون مارو بریزن که آره، این جزو برنامه‌های پیشفرض گنوم نیست 👺 شما ارزش مشارکت مارو ندارین 👺

@SohrabContents

🔶 انفجارهایی به سبک انفجارهای این روزهای لبنان و سوریه در‌ فیلم Jackpot ‏۲۰۲۴


@TheRaymondDev

توصیه میکنم اگر در حوزه نرم‌افزار تحت وب فعالیت میکنین این ۱۲ فاکتور رو مطالعه کنین.
https://12factor.net/

در لاراول orderByRaw بهتون این امکان رو میده که نتایج رو بتونید بر اساس یه سری محاسبات خاصی مرتب کنید.

مثلا ؟
میتونیم نتایج رو بر اساس اختلاف بین دو ستون ( قیمت و تخفیف) مرتب کنیم!
این آپشن یه سری جاها کدارو واقعا بهینه میکنه.
#laravel
@GoldenCodeir
(به منبع و مثالش دقت کنید 👇🏾)
https://x.com/laravelbackpack/status/1836004683594469864?t=IGgicccC4LllTLBm0hRviw&s=19