آموزشهونو (Hono)

درس ۴ از ۳۳، برنامه‌نویسی و علوم کامپیوتر، حدود ۳۱ دقیقه خواندن

API و REST به زبان ساده

جواب کوتاه

طبق سند مرجع وب (MDN)، API، کوتاه‌شده‌ی Application Programming Interface، مجموعه‌ای از امکانات و قاعده‌هاست که اجازه می‌ده یه برنامه، با یه برنامه‌ی دیگه کار کنه؛ یه قرارداد بین دو نرم‌افزار. REST، کوتاه‌شده‌ی Representational State Transfer، یه دسته قاعده‌ی طراحیه؛ ایده‌ی پایه‌ش اینه که یه منبع، مثل یه کتاب یا یه سفارش، با رفت‌وبرگشت‌های استاندارد کلاینت و سرور جابه‌جا می‌شه. توی یه API به سبک REST روی HTTP، هر منبع یه نشانی داره، مثل /books/42؛ و روش درخواست، کار رو تعیین می‌کنه: GET برای خوندن، POST برای ساختن، PUT برای جایگزین کردن، PATCH برای تغییر بخشی، و DELETE برای پاک کردن. سرور با یه کد وضعیت جواب می‌ده، مثل ۲۰۰ برای موفقیت، ۲۰۱ برای ساخته شدن، ۴۰۴ برای پیدا نشدن، و ۵۰۰ برای خطای سرور؛ و داده معمولا به شکل JSON ـه.

میز امانت یه کتابخونه

توی یه کتابخونه‌ی بزرگ، هر کتاب یه شماره‌ی قفسه داره. شما به میز امانت می‌رید و یه برگه‌ی کوچیک پر می‌کنید: «کتاب شماره‌ی ۴۲ رو می‌خوام ببینم»، یا «این کتاب تازه رو اضافه کنید»، یا «کتاب ۴۲ رو پس می‌دم». کتابدار، برگه رو می‌خونه، کار رو انجام می‌ده، و یه جواب کوتاه می‌ده: «بفرمایید»، «همچین کتابی نداریم»، یا «اجازه‌ی این کار رو ندارید».

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

API چیست

طبق سند مرجع وب، یعنی MDN، API، کوتاه‌شده‌ی Application Programming Interface، یعنی رابط برنامه‌نویسی اپلیکیشن، مجموعه‌ای از امکانات و قاعده‌هاست، توی یه نرم‌افزار، که اجازه می‌ده با اون نرم‌افزار، از راه نرم‌افزار کار کنید؛ نه از راه رابط کاربری، که مال آدم‌هاست.

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

API، یه قرارداده

سند MDN، یه تصویر خوب داره: API رو می‌شه یه قرارداد ساده دید، بین برنامه‌ای که API رو ارائه می‌ده و چیزهای دیگه، مثل نرم‌افزار یا سخت‌افزار دیگران. قرارداد می‌گه: «اگه این‌طوری بپرسی، این‌طوری جواب می‌دم».

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

API ها همه‌جا هستن

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

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

HTTP: زبون مشترک

طبق سند MDN، HTTP پروتکلیه برای گرفتن منبع‌ها، مثل سندهای HTML؛ و پایه‌ی هر تبادل داده توی وبه. پروتکل (Protocol) یعنی یه دسته قاعده‌ی توافق‌شده برای حرف زدن دو طرف؛ مثل قاعده‌های نامه‌نگاری، که می‌گه نشانی کجا نوشته بشه و تمبر کجا بخوره.

همون سند می‌گه HTTP یه پروتکل کلاینت و سروره؛ یعنی درخواست رو گیرنده، معمولا مرورگر، شروع می‌کنه. و تاریخچه‌ش رو هم می‌گه: اوایل دهه‌ی ۱۹۹۰ طراحی شد، و چون قابل گسترشه، با زمان رشد کرده؛ امروز نه فقط برای گرفتن صفحه، که برای فرستادن فرم و گرفتن تیکه‌هایی از داده برای به‌روز کردن صفحه هم به کار می‌ره.

درخواست و جواب

طبق سند MDN، کلاینت و سرور، با رد و بدل کردن پیام‌های جدا با هم حرف می‌زنن، نه یه جریان پیوسته‌ی داده. پیام‌هایی که کلاینت می‌فرسته، درخواست (Request) نام دارن، و پیام‌هایی که سرور در جواب می‌فرسته، جواب (Response).

یه درخواست، چند تیکه داره: روش، مثل GET؛ نشانی، مثل /books/42؛ سرآیندها؛ و گاهی یه بدنه، مثلا وقتی یه فرم فرستاده می‌شه. یه جواب هم: کد وضعیت، مثل ۲۰۰؛ سرآیندها؛ و معمولا یه بدنه، مثلا اطلاعات کتاب. توی هونو، c.req درخواسته، و چیزی که c.json برمی‌گردونه، جواب.

کلاینت: عامل کاربر

سند MDN، کلاینت رو «عامل کاربر» (User-Agent) می‌نامه: هر ابزاری که از طرف کاربر کار می‌کنه. همون سند می‌گه بیشتر وقت‌ها، این نقش رو مرورگر بازی می‌کنه؛ ولی می‌تونه هر چیزی باشه، مثلا رباتی که وب رو می‌گرده تا فهرست یه موتور جستجو رو پر کنه، یا برنامه‌هایی که برنامه‌نویس‌ها برای خطایابی به کار می‌برن.

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

سرور

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

و برعکس هم: طبق همون سند، چند نرم‌افزار سرور می‌تونن روی یه ماشین باشن. یعنی «سرور»، بیشتر یه نقشه تا یه دستگاه. API ـی که با هونو می‌سازید، یه نرم‌افزار سروره؛ که می‌تونه کنار سرورهای دیگه، روی یه ماشین اجرا بشه.

چیزهایی که وسط راهن

سند MDN می‌گه بین مرورگر و سرور، کامپیوترها و دستگاه‌های زیادی پیام‌های HTTP رو جابه‌جا می‌کنن؛ و اون‌هایی که توی لایه‌ی کاربرد کار می‌کنن، پراکسی (Proxy) نام دارن. همون سند، چند کار پراکسی‌ها رو فهرست می‌کنه: کش کردن، فیلتر کردن، پخش بار بین چند سرور، احراز هویت، و ثبت رخدادها.

برای کسی که API می‌سازه، این یعنی درخواستی که به سرور شما می‌رسه، ممکنه از چند جای دیگه گذشته باشه؛ و جوابی که می‌دید، ممکنه وسط راه کش بشه. برای همین، سرآیندهایی که درباره‌ی کش هستن، مهمن؛ تا مثلا اطلاعات خصوصی یه کاربر، جایی کش نشه که یکی دیگه ببینه.

HTTP، بالای لایه‌ها

طبق سند MDN، HTTP یه پروتکل لایه‌ی کاربرده، که روی TCP، یا یه اتصال TCP رمزشده با TLS، فرستاده می‌شه. همون سند می‌گه بین مرورگر و سرور، در واقع دستگاه‌های بیشتری هست، مثل روتر و مودم؛ ولی به لطف طراحی لایه‌لایه‌ی وب، این‌ها توی لایه‌های پایین‌تر پنهونن.

برای ساختن API، لازم نیست لایه‌های پایین رو بشناسید؛ همون سند هم می‌گه این لایه‌ها، برای توضیح HTTP، بیشتر بی‌ربطن، هرچند برای پیدا کردن مشکل‌های شبکه مهمن. کافیه بدونید که HTTPS، یعنی همون HTTP، روی یه اتصال رمزشده؛ و هر API واقعی، باید روی HTTPS باشه.

HTTP ساده و خوندنیه

سند MDN می‌گه HTTP طوری طراحی شده که آدم‌ها بتونن بخوننش؛ حتی با پیچیدگی‌هایی که نسخه‌های تازه‌ش اضافه کردن. همون سند می‌گه پیام‌های HTTP رو آدم‌ها می‌تونن بخونن و بفهمن؛ که تست کردن رو برای برنامه‌نویس‌ها راحت‌تر، و پیچیدگی رو برای تازه‌کارها کمتر می‌کنه.

این، خبر خوبیه: یه درخواست HTTP، چند خط متن ساده‌ست، مثل «GET /books/42» و چند سرآیند. وقتی توی درس بعد، با curl یه درخواست بفرستید، می‌تونید کل درخواست و جواب رو، خط به خط، ببینید و بخونید. هیچ رمز و رازی در کار نیست.

سرآیندها

طبق سند MDN، سرآیندهای HTTP، که از نسخه‌ی ۱٫۰ اومدن، این پروتکل رو برای گسترش و آزمایش راحت کردن؛ حتی می‌شه با توافق کلاینت و سرور روی معنی یه سرآیند تازه، امکان تازه اضافه کرد.

سرآیند، یه جفت اسم و مقداره؛ مثل نوع محتوا، که می‌گه بدنه JSON ـه یا HTML؛ یا سرآیند اجازه، که توکن ورود کاربر رو می‌بره. توی درس قبل دیدیم که هونو، با c.header، سرآیند جواب رو تعیین می‌کنه؛ و با c.req، سرآیندهای درخواست رو می‌خونه.

HTTP بی‌حالته

یه ویژگی مهم که سند MDN روش تاکید داره: HTTP بی‌حالته؛ یعنی هیچ ربطی بین دو درخواستی که پشت سر هم، روی یه اتصال، فرستاده می‌شن، نیست. سرور، با هر درخواست، از اول شروع می‌کنه؛ مثل کتابداری که هیچ‌وقت چهره‌ها رو یادش نمی‌مونه.

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

REST چیست

طبق سند MDN، REST، کوتاه‌شده‌ی Representational State Transfer، یعنی انتقال حالت بازنمایی‌شده، به یه دسته قیدهای طراحی معماری نرم‌افزار گفته می‌شه، که سیستم‌های توزیع‌شده‌ی کارآمد، قابل اعتماد و قابل گسترش می‌سازن. همون سند، ایده‌ی پایه‌ش رو این‌طوری می‌گه: یه منبع، مثلا یه سند، از راه رفت‌وبرگشت‌های کلاینت و سرور، که شناخته‌شده، مستقل از زبان و استاندارد قابل اعتمادن، جابه‌جا می‌شه.

و یه نکته‌ی صادقانه هم داره: به API های HTTP، به‌طور عامیانه، API های RESTful یا سرویس‌های REST می‌گن، هرچند لزوما همه‌ی قیدهای REST رو رعایت نمی‌کنن. و برای تازه‌کارها، یه تعریف ساده می‌ده: می‌تونید فرض کنید یه API ـی REST، یعنی یه سرویس HTTP، که می‌شه با کتابخونه‌ها و ابزارهای استاندارد وب صداش زد.

منبع (Resource)

مهم‌ترین مفهوم REST، منبع (Resource) ـه: هر چیزی که API نگه می‌داره و می‌شه درباره‌ش حرف زد. توی یه API فروشگاه، محصول‌ها، سفارش‌ها، کاربرها و نظرها، همه منبعن. توی کتابخونه، کتاب‌ها و عضوها.

توی سبک REST، API رو به جای فهرستی از «کارها»، مثل «سفارش ثبت کن» یا «کتاب پیدا کن»، به شکل فهرستی از «منبع‌ها» طراحی می‌کنید؛ و کارها، با چند روش ثابت HTTP، روی همین منبع‌ها انجام می‌شن. این، API رو قابل پیش‌بینی می‌کنه: اگه بدونید با کتاب‌ها چطور کار کنید، تقریبا می‌دونید با عضوها هم چطور.

هر منبع، یه نشانی

توی یه API به سبک REST، هر منبع یه نشانی داره؛ و رسم رایج، این شکلیه: /books، برای کل مجموعه‌ی کتاب‌ها؛ و /books/42، برای یه کتاب خاص، با شماره‌ی ۴۲. اسم مجموعه، معمولا جمع و انگلیسیه، و شماره یا شناسه، بعدش میاد.

منبع‌های تودرتو هم همین‌طوری نوشته می‌شن: /books/42/reviews، یعنی نظرهای کتاب ۴۲. یه رسم مهم دیگه: توی نشانی، از اسم استفاده کنید، نه فعل. یعنی /books، نه /getBooks؛ چون کار، یعنی گرفتن، رو روش GET می‌گه، نه نشانی. درس پنجم، با مسیریابی هونو، همین نشانی‌ها رو می‌سازه.

روش‌های HTTP

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

  • GET: خوندن یه منبع.
  • POST: فرستادن یه چیز تازه به یه منبع؛ معمولا ساختن.
  • PUT: جایگزین کردن کامل یه منبع.
  • PATCH: تغییر بخشی از یه منبع.
  • DELETE: پاک کردن یه منبع.

سند MDN چند روش دیگه هم داره، مثل HEAD و OPTIONS؛ که کمتر مستقیم باهاشون کار دارید.

GET: خوندن

طبق سند MDN، روش GET، بازنمایی منبع مشخص‌شده رو درخواست می‌کنه؛ و درخواست‌هایی با GET، فقط باید داده بگیرن، و نباید بدنه داشته باشن. یعنی GET /books، فهرست کتاب‌ها رو می‌خواد؛ و GET /books/42، کتاب ۴۲ رو.

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

POST: ساختن

طبق سند MDN، روش POST، یه موجودیت رو به منبع مشخص‌شده می‌فرسته، و اغلب باعث تغییر حالت یا اثرهای جانبی روی سرور می‌شه. توی API ها، رایج‌ترین کاربردش، ساختن یه چیز تازه‌ست: POST /books، با اطلاعات یه کتاب تازه توی بدنه، اون کتاب رو به مجموعه اضافه می‌کنه.

معمولا، سرور شماره‌ی کتاب تازه رو خودش تعیین می‌کنه، و توی جواب برمی‌گردونه؛ با کد وضعیت ۲۰۱، که چند بخش بعد می‌بینیم. فرم‌های وب هم، بیشتر وقت‌ها، با POST فرستاده می‌شن؛ همون‌طور که سند MDN، توی معرفی HTTP، از فرستادن نتیجه‌ی فرم‌های HTML حرف می‌زنه.

PUT و PATCH: تغییر

طبق سند MDN، روش PUT، همه‌ی بازنمایی‌های فعلی منبع مقصد رو، با محتوای درخواست، جایگزین می‌کنه؛ و روش PATCH، تغییرهای بخشی رو روی یه منبع اعمال می‌کنه. فرقشون، ساده ولی مهمه.

فرض کنید کتاب ۴۲، اسم، نویسنده و سال انتشار داره، و می‌خواید فقط سالش رو درست کنید. با PATCH /books/42، فقط سال تازه رو می‌فرستید. با PUT /books/42، باید کل کتاب رو، با هر سه ویژگی، بفرستید؛ چون جایگزین کامله. اگه با PUT، فقط سال رو بفرستید، ممکنه اسم و نویسنده پاک بشن.

DELETE: پاک کردن

طبق سند MDN، روش DELETE، منبع مشخص‌شده رو پاک می‌کنه. DELETE /books/42، کتاب ۴۲ رو از مجموعه برمی‌داره. ساده‌ترین روشه؛ ولی خطرناک‌ترین هم هست، چون معمولا برگشت‌پذیر نیست.

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

روش‌های امن و تکرارپذیر

سند MDN می‌گه بعضی ویژگی‌ها، بین چند روش مشترکن: روش‌ها می‌تونن امن (Safe)، تکرارپذیر (Idempotent) یا قابل کش (Cacheable) باشن. روش امن، یعنی چیزی رو روی سرور عوض نمی‌کنه؛ مثل GET. روش تکرارپذیر، یعنی اگه همون درخواست رو چند بار بفرستید، نتیجه همون یه باره.

مثلا DELETE /books/42، تکرارپذیره: بار اول پاک می‌کنه، و بار دوم و سوم، چیزی برای پاک کردن نیست؛ نتیجه همونه. ولی POST /books، تکرارپذیر نیست: هر بار، یه کتاب تازه می‌سازه. برای همین، اگه اینترنت قطع و وصل بشه و کلاینت یه درخواست POST رو دوباره بفرسته، ممکنه دو سفارش ثبت بشه؛ یه مشکل واقعی که API های خوب، براش فکر می‌کنن.

کد وضعیت

طبق سند MDN، کدهای وضعیت جواب HTTP، نشون می‌دن یه درخواست مشخص، با موفقیت انجام شده یا نه. همون سند می‌گه این کدها، توی یه استاندارد رسمی تعریف شدن؛ و اگه یه کد دیدید که توی فهرست نیست، احتمالا غیراستاندارد و مال نرم‌افزار خود اون سروره.

کد وضعیت، اولین چیزیه که کلاینت نگاه می‌کنه؛ حتی پیش از خوندن بدنه. یه API خوب، همیشه کد درست برمی‌گردونه: اگه کتاب پیدا نشد، ۴۰۴، نه ۲۰۰ با یه پیام «پیدا نشد» توی بدنه. چون برنامه‌ای که API رو صدا می‌زنه، از روی کد، تصمیم می‌گیره چی کار کنه.

پنج دسته‌ی کد

طبق سند MDN، جواب‌ها توی پنج دسته‌ان، که از رقم اول کد شناخته می‌شن:

  • ۱۰۰ تا ۱۹۹: جواب‌های اطلاع‌رسانی.
  • ۲۰۰ تا ۲۹۹: جواب‌های موفق.
  • ۳۰۰ تا ۳۹۹: پیام‌های هدایت به جای دیگه.
  • ۴۰۰ تا ۴۹۹: خطاهای کلاینت.
  • ۵۰۰ تا ۵۹۹: خطاهای سرور.

قاعده‌ی ساده‌ش: ۴ یعنی «تو اشتباه کردی»؛ ۵ یعنی «من اشتباه کردم». یعنی ۴xx، کلاینت باید درخواستش رو درست کنه؛ ۵xx، مشکل سمت سروره.

کدهایی که هر روز می‌بینید

از روی فهرست سند MDN، این‌ها پرکاربردترینن:

  • ۲۰۰ OK: درخواست موفق بود؛ معنی موفقیت به روش بستگی داره.
  • ۲۰۱ Created: موفق بود و یه منبع تازه ساخته شد؛ معمولا بعد از POST.
  • ۲۰۴ No Content: موفق بود، ولی محتوایی برای فرستادن نیست؛ مثلا بعد از پاک کردن.
  • ۴۰۰ Bad Request: سرور، به خاطر چیزی که خطای کلاینت به نظر میاد، مثل نوشتار اشتباه درخواست، کار رو انجام نمی‌ده.
  • ۴۰۴ Not Found: سرور، منبع خواسته‌شده رو پیدا نمی‌کنه.
  • ۴۰۹ Conflict: درخواست با حالت فعلی سرور تناقض داره.
  • ۵۰۰ Internal Server Error: سرور به وضعیتی خورده که نمی‌دونه چطور باهاش کنار بیاد.

۴۰۱ یا ۴۰۳؟

دو کد هستن که خیلی وقت‌ها قاطی می‌شن. طبق سند MDN، ۴۰۱، با اینکه اسمش «Unauthorized» ـه، در واقع یعنی «احراز هویت نشده»؛ یعنی سرور نمی‌دونه شما کی هستید، مثلا چون وارد نشدید. و ۴۰۳ Forbidden، یعنی کلاینت حق دسترسی به این محتوا رو نداره؛ سرور می‌دونه شما کی هستید، ولی اجازه ندارید.

توی تصویر کتابخونه: ۴۰۱ یعنی «کارت عضویتت رو نشون بده»؛ ۴۰۳ یعنی «کارتت رو دیدم، ولی این بخش، فقط برای کارمندهاست». ایستگاه ششم، که ورود و دسترسیه، این دو رو دقیق به کار می‌بره.

JSON: شکل داده

توی درس قبل گفتیم بیشتر API ها، داده رو با JSON می‌فرستن. یه کتاب، به شکل JSON، این‌طوری می‌شه: {"id": 42, "title": "شازده کوچولو", "year": 1943}. کلیدها توی نقل‌قول، دونقطه، و مقدار؛ و جفت‌ها، با ویرگول جدا. فهرست کتاب‌ها، یه آرایه از همین‌هاست، توی کروشه.

سند MDN، یه صفحه‌ی کامل درباره‌ی JSON داره، و می‌گه یه قالب متنیه که شبیه نوشتار شیء جاوااسکریپته؛ ولی مستقل از جاوااسکریپت، و تقریبا همه‌ی زبان‌ها می‌تونن بخوننش و بنویسنش. برای همین، یه API که با هونو و تایپ‌اسکریپت ساختید، می‌تونه به یه اپ گوشی یا یه برنامه‌ی پایتونی هم جواب بده.

یه API کامل کتاب، روی کاغذ

بیاید همه‌ی این‌ها رو کنار هم بذاریم، برای یه API کتاب:

  • GET /books: فهرست کتاب‌ها؛ جواب ۲۰۰ با یه آرایه‌ی JSON.
  • GET /books/42: کتاب ۴۲؛ جواب ۲۰۰، یا ۴۰۴ اگه نبود.
  • POST /books: ساختن کتاب تازه؛ جواب ۲۰۱ با کتاب ساخته‌شده، یا ۴۰۰ اگه ورودی اشتباه بود.
  • PATCH /books/42: تغییر بخشی؛ جواب ۲۰۰ با کتاب تازه.
  • DELETE /books/42: پاک کردن؛ جواب ۲۰۴، یا ۴۰۴ اگه نبود.
  • هر تغییری بی ورود: ۴۰۱؛ و تغییر کتابی که مال شما نیست: ۴۰۳.

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

اشتباه‌های رایج طراحی API

این اشتباه‌ها، توی API های تازه‌کارها خیلی رایجن:

  • فعل توی نشانی: /getBooks یا /deleteBook/42، به جای روش درست.
  • عوض کردن داده با GET.
  • برگردوندن ۲۰۰ برای همه‌چیز، حتی خطا، با یه پیام خطا توی بدنه.
  • برگردوندن ۵۰۰ وقتی ورودی کاربر اشتباه بوده؛ که باید ۴۰۰ باشه.
  • نشونی‌های ناهمخوان: /books و /Author و /order_items توی یه API.

هر کدوم، API رو برای کسی که ازش استفاده می‌کنه، غیرقابل پیش‌بینی می‌کنه.

جواب کوتاه

اگه کسی پرسید «API و REST چیه»:

API، قرارداد بین دو برنامه‌ست: اگه این‌طوری بپرسی، این‌طوری جواب می‌دم. REST یه سبک طراحی API ـه روی HTTP، که توش هر منبع یه نشانی داره و کارها با چند روش استاندارد انجام می‌شن: GET خوندن، POST ساختن، PUT و PATCH تغییر، DELETE پاک کردن؛ و سرور با کد وضعیت، مثل ۲۰۰، ۴۰۴ یا ۵۰۰، و معمولا داده‌ی JSON جواب می‌ده.

چند باور رایج

  • «API فقط مال سرورهاست.» مرورگر هم API داره؛ طبق MDN، معنای گسترده‌ای داره.
  • «هر API ـی HTTP، کاملا REST ـه.» طبق MDN، لزوما همه‌ی قیدها رو رعایت نمی‌کنه.
  • «PUT و PATCH یه کار می‌کنن.» PUT جایگزین کامل، PATCH تغییر بخشی.
  • «۴۰۱ و ۴۰۳ فرقی ندارن.» ۴۰۱ ناشناس؛ ۴۰۳ شناخته‌شده بی اجازه.
  • «سرور، کاربر رو بین درخواست‌ها یادش می‌مونه.» HTTP بی‌حالته.

یه مثال

یه تیم کوچیک، API یه اپ یادداشت رو ساخته بود، با نشانی‌هایی مثل /getNotes، /addNote و /removeNote؛ و همه با POST، و همه با جواب ۲۰۰، حتی وقتی یادداشت پیدا نمی‌شد. وقتی یه برنامه‌نویس تازه اومد تا اپ گوشیش رو بسازه، دو روز وقت گذاشت فقط تا بفهمه هر نشانی چی می‌خواد و کی خطا داده.

تیم، API رو به سبک REST بازنویسی کرد: /notes و /notes/42، با GET، POST، PATCH و DELETE، و کدهای درست. برنامه‌نویس بعدی، با دیدن فهرست شش‌خطی، بی هیچ توضیحی، شروع به کار کرد؛ و اپ گوشی، از روی کد وضعیت، می‌دونست کی پیام «یادداشت پیدا نشد» نشون بده.

تمرین امروز

امروز، API یه چیز آشنا رو، روی کاغذ، به سبک REST طراحی کنید.

  1. یه موضوع انتخاب کنید؛ مثلا فهرست دستور پخت‌های خونه.
  2. منبع‌ها رو بنویسید؛ مثلا دستور پخت، و نظرهای هر دستور.
  3. برای هر منبع، نشانی‌ها رو با رسم REST بنویسید.
  4. برای هر کار، روش و کد وضعیت موفق رو بنویسید.
  5. برای هر کار، یه حالت خطا و کد وضعیتش رو بنویسید؛ مثلا ۴۰۴ یا ۴۰۰.

درس بعدی، پروژه‌ی هونو رو روی کامپیوترتون می‌سازه و اولین درخواست واقعی رو جواب می‌ده: ساختن پروژه و اولین مسیر.

جمع‌بندی. آنچه از این درس با خودتان می‌برید.

  • API، قرارداد بین دو برنامه‌ست.
  • REST: هر منبع یه نشانی، و چند روش استاندارد برای کار باهاش.
  • GET خوندن، POST ساختن، PUT جایگزینی، PATCH تغییر بخشی، DELETE پاک کردن.
  • کد وضعیت: ۲xx موفق، ۴xx خطای کلاینت، ۵xx خطای سرور.
  • HTTP بی‌حالته؛ هر درخواست، همه‌ی چیزهای لازم رو با خودش داره.

خودتون رو بسنجید

۱۵ پرسش، هر بار تازه از میان ۳۰ پرسش این درس. آخرش فقط کارنامه رو می‌بینید: چند تا درست، چند تا نادرست.

خودتون رو بسنجید

۱۵ پرسش

  • هر بار پرسش‌ها و ترتیب گزینه‌ها عوض می‌شه.
  • تا آخر نمی‌گیم کدوم جواب درست بوده؛ می‌تونید برگردید و جوابتون رو عوض کنید.
  • آخرش کارنامه می‌گیرید: چند تا درست، چند تا نادرست.
  • اگه وسطش بستید، دوباره که باز کنید از همون‌جا ادامه می‌دید.

فصل‌های این درس

درس بعد