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

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

کلید واژه: API یا Application Programming Interface

چرا به API نیاز داریم:

تصور کنید برنامه‌ای نوشته‌اید که سرویسی را ارائه می‌دهد، مانند یک مدل زبانی بزرگ که بر روی داده‌های پزشکی آموزش دیده است. حال می‌خواهید دیگران بتوانند از این سرویس استفاده کنند، بدون اینکه به کد اصلی برنامه دسترسی داشته باشند یا امکان تغییر آن را داشته باشند. تنها چیزی که لازم است این است که بتوانند درخواست‌هایی ارسال کنند و پاسخ مورد نظر را دریافت نمایند.

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

هر دو سناریوی فوق را می‌توان با کمک رابط برنامه نویسی کاربردی (API) پیاده‌سازی کرد.

جزییات API Call:

هر API برای ارسال درخواست (API call) شامل بخش‌های زیر است:

* API Endpoint: آدرس (URL) برای دسترسی به سرویس خاص.

* Method: عملیات مورد نظر مانند GET (دریافت)، POST (ارسال)، PUT (به‌روزرسانی)، DELETE (حذف).

* Header: اطلاعات اضافی همراه درخواست، مانند کلید API (API Key).

* Body: اطلاعات اصلی درخواست (در صورت نیاز).

پس از ارسال درخواست، پاسخی دریافت می‌شود که معمولاً شامل موارد زیر است:

* Status Code: کدی که وضعیت پاسخ را مشخص می‌کند، مانند 200 (موفقیت) یا 500 (خطای سرور).

* Body: پاسخ، که معمولاً در قالب JSON ارائه می‌شود.

پارامترها:

برای ارسال پارامترها همراه با درخواست، دو روش اصلی وجود دارد:

روش اول: Path Parameters (پارامترهای مسیر)

در این روش، پارامتر مستقیماً در خود آدرس قرار می‌گیرد.

مثال:

https://api.weather.com/weather/Vienna

در آدرس بالا، Vienna به عنوان پارامتر در خود URL قرار گرفته است.

روش دوم: Query Parameters (پارامترهای پرس‌وجو)

این روش امکان ارسال تعداد بیشتری پارامتر را فراهم می‌کند و از سینتکس زیر استفاده می‌شود:

https://api.weather.com/weather?city=Vienna&year=2026

* علامت ? نشان می‌دهد که پارامترها شروع می‌شوند.

* هر پارامتر به صورت key=value تعریف می‌شود.

* پارامترها با علامت & از یکدیگر جدا می‌شوند.

استاندارد RESTful API

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

* /getuser

* /deleteuser

* /updatename

* /updateage

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

مثال:

* getuser?id=253/ (روش قدیمی) معادل GET /user/253 (روش RESTful)

* delete?user=123/ (روش قدیمی) معادل DELETE /user/123 (روش RESTful)

در استاندارد RESTful، ما از متدهای HTTP برای انجام عملیات بر روی منابع (مانند کاربر) استفاده می‌کنیم و آدرس‌ها ساختار منظم‌تری دارند.

نحوه کار با API در پایتون:

ارسال درخواست با requests:

import requests

url = "https://api.example.com/users"  # نمونه آدرس

response = requests.get(url)

print(f"status code: {response.status_code}")
print(f"headers: {response.headers}")
print(f"data: {response.json()}")

ایجاد داده با متد با POST:

در صورتی که headers نداشتیم می توانیم آن را حذف کنیم و چیزی ارسال نکنیم.

import requests

url = "https://api.example.com/users"  # نمونه آدرس

headers = {
    "Authorization": "Bearer YOUR_TOKEN_HERE"
}

data = {"name" : "Ahmadreza",
        "family" : "Sezavar",
        "job" : "AI engineer"}

response = requests.post(url, headers = headers, json=data)

response.raise_for_status()

print("Data created successfully.")
print("Response:", response.json())

نحوه ایجاد یک سرویس WebAPI

می توانیم از فریمورک های مختلفی برای اینکار استفاده کنیم مانند Flask, FastAPI

در اینجا ما از FastAPI به دلیل سرعت بالا استفاده می کنیم، هم چنین از uvicorn برای ایجاد یک سرور

from fastapi import FastAPI

app = FastAPI()

# یک دیکشنری ساده به عنوان حافظه موقت
db = {}

@app.get("/")
def root():
    return {"message": "This is the main page"}

# برای ایجاد کاربر جدید
@app.post("/users/{user_id}")
def create_user(user_id: int, name: str):
    db[user_id] = name
    return {"message": "user added"}

# برای دیدن کاربران اضافه شده
@app.get("/users")
def get_users():
    return db

نحوه اجرا:

uvicorn main:app --reload