30-Days-Of-Python/Persain/28_API.md

<div align="center">
  <h1> ۳۰ روز با پایتون: روز ۲۸ - API </h1>
  <a class="header-badge" target="_blank" href="https://www.linkedin.com/in/asabeneh/">
  <img src="https://img.shields.io/badge/style--5eba00.svg?label=LinkedIn&logo=linkedin&style=social">
  </a>
  <a class="header-badge" target="_blank" href="https://twitter.com/Asabeneh">
  <img alt="Twitter Follow" src="https://img.shields.io/twitter/follow/asabeneh?style=social">
  </a>

<sub>نویسنده:
<a href="https://www.linkedin.com/in/asabeneh/" target="_blank">Asabeneh Yetayeh</a><br>
<small>ویرایش دوم: جولای، ۲۰۲۱</small>
</sub>

</div>
</div>

[<< روز ۲۷](./27_python_with_mongodb.md) | [روز ۲۹ >>](./29_building_API.md)

![30DaysOfPython](../images/30DaysOfPython_banner3@2x.png)

- [📘 روز ۲۸](#-روز-۲۸)
- [واسط برنامه‌نویسی کاربردی (API)](#واسط-برنامهنویسی-کاربردی-api)
  - [API](#api)
  - [ساخت API](#ساخت-api)
  - [HTTP (پروتکل انتقال ابرمتن)](#http-پروتکل-انتقال-ابرمتن)
  - [ساختار HTTP](#ساختار-http)
  - [خط درخواست اولیه (خط وضعیت)](#خط-درخواست-اولیه-خط-وضعیت)
    - [خط پاسخ اولیه (خط وضعیت)](#خط-پاسخ-اولیه-خط-وضعیت)
    - [فیلدهای سرآیند](#فیلدهای-سرآیند)
    - [بدنه پیام](#بدنه-پیام)
    - [متدهای درخواست](#متدهای-درخواست)
  - [💻 تمرینات: روز ۲۸](#-تمرینات-روز-۲۸)

# 📘 روز ۲۸

# واسط برنامه‌نویسی کاربردی (API)

## API

API مخفف Application Programming Interface (واسط برنامه‌نویسی کاربردی) است. نوعی از API که در این بخش به آن خواهیم پرداخت، APIهای وب (Web APIs) خواهند بود.
APIهای وب، واسط‌های تعریف‌شده‌ای هستند که از طریق آن‌ها تعاملات بین یک شرکت و برنامه‌هایی که از دارایی‌های آن استفاده می‌کنند، رخ می‌دهد، که همچنین یک توافق‌نامه سطح خدمات (SLA) برای مشخص کردن ارائه‌دهنده عملکردی و افشای مسیر سرویس یا URL برای کاربران API آن است.

در زمینه توسعه وب، API به عنوان مجموعه‌ای از مشخصات، مانند پیام‌های درخواست پروتکل انتقال ابرمتن (HTTP)، به همراه تعریفی از ساختار پیام‌های پاسخ، معمولاً در قالب XML یا نشانه‌گذاری شیء جاوا اسکریپت (JSON) تعریف می‌شود.

API وب از خدمات وب مبتنی بر پروتکل دسترسی ساده به اشیاء (SOAP) و معماری سرویس‌گرا (SOA) به سمت منابع وب با سبک انتقال حالت بازنمودی (REST) مستقیم‌تر حرکت کرده است.

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

با استفاده از API، محتوایی که در یک مکان به صورت پویا ایجاد می‌شود، می‌تواند در چندین مکان در وب پست و به‌روز شود.

به عنوان مثال، REST API توییتر به توسعه‌دهندگان اجازه می‌دهد تا به داده‌های اصلی توییتر دسترسی داشته باشند و Search API متدهایی را برای تعامل توسعه‌دهندگان با داده‌های جستجو و ترندهای توییتر فراهم می‌کند.

بسیاری از برنامه‌ها نقاط پایانی (end points) API ارائه می‌دهند. برخی از نمونه‌های API مانند [API کشورها](https://restcountries.eu/rest/v2/all) و [API نژاد گربه‌ها](https://api.thecatapi.com/v1/breeds).

در این بخش، ما یک API به سبک RESTful را پوشش خواهیم داد که از متدهای درخواست HTTP برای دریافت (GET)، قرار دادن (PUT)، ارسال (POST) و حذف (DELETE) داده‌ها استفاده می‌کند.

## ساخت API

API به سبک RESTful یک واسط برنامه‌نویسی کاربردی (API) است که از درخواست‌های HTTP برای دریافت (GET)، قرار دادن (PUT)، ارسال (POST) و حذف (DELETE) داده‌ها استفاده می‌کند. در بخش‌های قبلی، ما با پایتون، فلسک و مانگو‌دی‌بی آشنا شدیم. ما از دانشی که به دست آورده‌ایم برای توسعه یک API به سبک RESTful با استفاده از پایتون فلسک و پایگاه داده مانگو‌دی‌بی استفاده خواهیم کرد. هر برنامه‌ای که عملیات CRUD (ایجاد، خواندن، به‌روزرسانی، حذف) را دارد، یک API برای ایجاد داده، دریافت داده، به‌روزرسانی داده یا حذف داده از پایگاه داده دارد.

برای ساخت یک API، خوب است که پروتکل HTTP و چرخه درخواست و پاسخ HTTP را درک کنید.

## HTTP (پروتکل انتقال ابرمتن)

HTTP یک پروتکل ارتباطی تثبیت‌شده بین یک کلاینت و یک سرور است. کلاینت در این مورد یک مرورگر و سرور مکانی است که شما به داده‌ها دسترسی پیدا می‌کنید. HTTP یک پروتکل شبکه است که برای تحویل منابع، که می‌تواند فایل‌هایی در وب جهان‌گستر باشد، استفاده می‌شود، چه این منابع فایل‌های HTML، فایل‌های تصویری، نتایج کوئری، اسکریپت‌ها یا انواع دیگر فایل‌ها باشند.

یک مرورگر یک کلاینت HTTP است زیرا درخواست‌ها را به یک سرور HTTP (وب سرور) ارسال می‌کند، که سپس پاسخ‌ها را به کلاینت باز می‌گرداند.

## ساختار HTTP

HTTP از مدل کلاینت-سرور استفاده می‌کند. یک کلاینت HTTP یک اتصال را باز کرده و یک پیام درخواست به یک سرور HTTP ارسال می‌کند و سرور HTTP یک پیام پاسخ را که همان منابع درخواستی است، برمی‌گرداند. هنگامی که چرخه درخواست و پاسخ کامل می‌شود، سرور اتصال را می‌بندد.

![چرخه درخواست و پاسخ HTTP](../images/http_request_response_cycle.png)

فرمت پیام‌های درخواست و پاسخ مشابه است. هر دو نوع پیام دارای:

- یک خط اولیه،
- صفر یا چند خط سرآیند،
- یک خط خالی (یعنی یک CRLF به تنهایی)، و
- یک بدنه پیام اختیاری (به عنوان مثال، یک فایل، یا داده‌های کوئری، یا خروجی کوئری).

بیایید با مراجعه به این سایت یک مثال از پیام‌های درخواست و پاسخ را ببینیم: https://thirtydaysofpython-v1-final.herokuapp.com/. این سایت بر روی داینو رایگان Heroku مستقر شده است و ممکن است در برخی ماه‌ها به دلیل درخواست بالا کار نکند. از این کار حمایت کنید تا سرور همیشه در حال اجرا باشد.

![سرآیند درخواست و پاسخ](../images/request_response_header.png)

## خط درخواست اولیه (خط وضعیت)

خط درخواست اولیه با خط پاسخ متفاوت است.
یک خط درخواست دارای سه بخش است که با فاصله از هم جدا شده‌اند:

- نام متد (GET, POST, HEAD)
- مسیر منبع درخواستی،
- نسخه HTTP مورد استفاده. به عنوان مثال GET / HTTP/1.1

GET رایج‌ترین متد HTTP است که به دریافت یا خواندن منبع کمک می‌کند و POST یک متد درخواست رایج برای ایجاد منبع است.

### خط پاسخ اولیه (خط وضعیت)

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

- نسخه HTTP
- کد وضعیت پاسخ که نتیجه درخواست را می‌دهد، و یک دلیل که کد وضعیت را توصیف می‌کند. نمونه‌هایی از خطوط وضعیت عبارتند از:
  HTTP/1.0 200 OK
  یا
  HTTP/1.0 404 Not Found
  نکات:

رایج‌ترین کدهای وضعیت عبارتند از:
200 OK: درخواست با موفقیت انجام شد و منبع حاصل (مثلاً فایل یا خروجی اسکریپت) در بدنه پیام بازگردانده می‌شود.
500 خطای سرور
لیست کاملی از کدهای وضعیت HTTP را می‌توان در [اینجا](https://httpstatuses.com/) یافت. همچنین می‌توان آن را در [اینجا](https://httpstatusdogs.com/) پیدا کرد.

### فیلدهای سرآیند

همانطور که در تصویر بالا مشاهده کردید، خطوط سرآیند اطلاعاتی در مورد درخواست یا پاسخ، یا در مورد شیء ارسال شده در بدنه پیام ارائه می‌دهند.

```sh
GET / HTTP/1.1
Host: thirtydaysofpython-v1-final.herokuapp.com
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.79 Safari/537.36
Sec-Fetch-User: ?1
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
Sec-Fetch-Site: same-origin
Sec-Fetch-Mode: navigate
Referer: https://thirtydaysofpython-v1-final.herokuapp.com/post
Accept-Encoding: gzip, deflate, br
Accept-Language: en-GB,en;q=0.9,fi-FI;q=0.8,fi;q=0.7,en-CA;q=0.6,en-US;q=0.5,fr;q=0.4
```

### بدنه پیام

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

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

سرآیند Content-Type: نوع MIME داده‌های موجود در بدنه را می‌دهد (text/html, application/json, text/plain, text/css, image/gif).
سرآیند Content-Length: تعداد بایت‌های موجود در بدنه را می‌دهد.

### متدهای درخواست

GET، POST، PUT و DELETE متدهای درخواست HTTP هستند که ما برای پیاده‌سازی یک API یا یک برنامه با عملیات CRUD از آنها استفاده خواهیم کرد.

1. GET: متد GET برای بازیابی و دریافت اطلاعات از سرور مشخص با استفاده از یک URI مشخص استفاده می‌شود. درخواست‌هایی که از GET استفاده می‌کنند فقط باید داده‌ها را بازیابی کنند و نباید هیچ تأثیر دیگری بر داده‌ها داشته باشند.

2. POST: درخواست POST برای ایجاد داده و ارسال داده به سرور استفاده می‌شود، به عنوان مثال، ایجاد یک پست جدید، آپلود فایل و غیره با استفاده از فرم‌های HTML.

3. PUT: تمام بازنمایی‌های فعلی منبع هدف را با محتوای آپلود شده جایگزین می‌کند و ما از آن برای تغییر یا به‌روزرسانی داده‌ها استفاده می‌کنیم.

4. DELETE: داده‌ها را حذف می‌کند.

## 💻 تمرینات: روز ۲۸

1. در مورد API و HTTP مطالعه کنید.

🎉 تبریک می‌گویم ! 🎉

[<< روز ۲۷](./27_python_with_mongodb.md) | [روز ۲۹ >>](./29_building_API.md)