بتل کد Battle Codeدارد باز می‌شود…

HTTP

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

a یا an؟ به صدا گوش بده

انتخاب میان a و an به صدای اول کلمه بستگی دارد، نه به حرف اولش. HTTP با صدای «اِی» شروع می‌شود (اِیچ)، پس می‌گویند an HTTP request. ولی URL با صدای «ی» شروع می‌شود (یو)، پس می‌گویند a URL. همین‌طور: an API، an SDK، a GET request.

هشت کلمه‌ی این درس

HTTP (اِیچ‌تی‌تی‌پی): پروتکل وب؛ زبان گفت‌وگوی مرورگر و سرور

HTTP قراردادی است که مرورگر و سرور با آن حرف می‌زنند. اسمش یعنی «پروتکل انتقال ابرمتن»؛ hypertext متنی است که لینک دارد، یعنی همان صفحه‌ی وب. قاعده‌اش ساده است: کلاینت یک request می‌فرستد، سرور یک response برمی‌گرداند و تمام. همه‌ی این پیام‌ها متن ساده‌اند، برای همین می‌توانی آن‌ها را با چشم بخوانی. APIها هم روی همین پروتکل کار می‌کنند.

The API uses HTTP to send and receive data.

این API برای فرستادن و گرفتن داده از HTTP استفاده می‌کند.

HTTPS (اِیچ‌تی‌تی‌پی‌اِس): نسخه‌ی امن و رمزشده‌ی HTTP

S آخرش یعنی Secure (امن). HTTPS همان HTTP است، با این فرق که پیام‌ها قبل از فرستادن رمز می‌شوند. HTTP مثل کارت‌پستال است: هر کس در راه دستش برسد می‌تواند بخواندش. HTTPS مثل نامه‌ی داخل پاکت دربسته است: فقط گیرنده بازش می‌کند. نشانه‌اش قفل کوچک کنار نشانی در مرورگر است. هیچ‌وقت رمز عبور را در صفحه‌ای که HTTPS ندارد وارد نکن.

Always use HTTPS when you send passwords.

هر وقت رمز عبور می‌فرستی، حتماً از HTTPS استفاده کن.

HTTP method (اِیچ‌تی‌تی‌پی مِتِد): نوع کاری که درخواست از سرور می‌خواهد

method یعنی روش. هر درخواست HTTP با یک کلمه شروع می‌شود که می‌گوید با آن نشانی چه کاری می‌خواهی بکنی؛ به این کلمه HTTP method می‌گویند. چهار تای اصلی این‌ها هستند: GET (بگیر)، POST (چیز تازه بفرست)، PUT یا PATCH (عوض کن) و DELETE (پاک کن). یک نشانی با متدهای مختلف کارهای مختلف می‌کند: GET /users فهرست را می‌دهد و POST /users یک کاربر تازه می‌سازد.

This endpoint does not support the DELETE HTTP method.

این اندپوینت از متد DELETE پشتیبانی نمی‌کند.

GET request (گِت ریکوئِست): درخواستی که فقط چیزی را می‌گیرد

get یعنی گرفتن. GET request درخواستی است که می‌گوید «این را به من بده» و چیزی را روی سرور عوض نمی‌کند، مثل نگاه کردن به ویترین مغازه. هر بار که نشانی‌ای را در مرورگر می‌زنی یا روی لینکی کلیک می‌کنی، یک GET request فرستاده‌ای. این درخواست body ندارد؛ اگر لازم باشد چیزی همراهش بفرستی، در خود نشانی و بعد از علامت سؤال می‌آید.

Send a GET request to /products to see all products.

برای دیدن همه‌ی محصول‌ها، یک درخواست GET به ‎/products بفرست.

POST request (پُست ریکوئِست): درخواستی که داده‌ی تازه به سرور می‌فرستد

post در انگلیسی یعنی پست کردن نامه. POST request درخواستی است که چیزی را برای سرور می‌فرستد تا با آن کاری بکند: ثبت‌نام، فرستادن پیام، ثبت سفارش. داده در body درخواست می‌رود، نه در نشانی. فرقش با GET مثل فرق نگاه کردن به ویترین با پر کردن و تحویل دادن فرم سفارش است: بعد از POST معمولاً چیزی روی سرور عوض شده است.

The form sends a POST request when you click Save.

وقتی روی Save می‌زنی، فرم یک درخواست POST می‌فرستد.

header (هِدِر): سرآیند؛ اطلاعات کناری بالای درخواست یا پاسخ

head یعنی سر و header چیزی است که در سر و بالای یک چیز می‌آید. در HTTP، هدرها خط‌هایی به شکل «اسم: مقدار» هستند که قبل از داده‌ی اصلی می‌آیند و درباره‌ی پیام توضیح می‌دهند: داده چه قالبی دارد، فرستنده کیست، به چه زبانی جواب بده. مثل نوشته‌های روی پاکت نامه: خود نامه نیستند، ولی بدون آن‌ها نامه به مقصد نمی‌رسد.

Add your token to the Authorization header.

توکنت را به هدر Authorization اضافه کن.

body (بادی): بدنه؛ خود داده‌ی درخواست یا پاسخ

body یعنی بدن. هر پیام HTTP یک «سر» دارد (هدرها) و یک «بدن» (body). body خود چیزی است که فرستاده می‌شود: در پاسخ، صفحه‌ی HTML یا داده‌ی JSON؛ در درخواست POST، اطلاعات فرمی که پر کرده‌ای. اگر هدرها نوشته‌های روی پاکت باشند، body نامه‌ی داخل پاکت است. درخواست GET معمولاً body ندارد.

The request body must be valid JSON.

بدنه‌ی درخواست باید JSON درست باشد.

status code (اِستِیتِس کُد): کد وضعیت؛ عدد سه‌رقمی نتیجه‌ی درخواست

status یعنی وضعیت. هر پاسخ HTTP با یک عدد سه‌رقمی شروع می‌شود که در یک نگاه می‌گوید چه شد؛ به آن status code می‌گویند. رقم اول دسته را نشان می‌دهد: 2xx یعنی درست انجام شد (200)، 3xx یعنی برو جای دیگر (301)، 4xx یعنی اشتباه از طرف تو بود (404 پیدا نشد)، 5xx یعنی اشتباه از طرف سرور بود (500). مثل چراغ راهنما: قبل از خواندن جواب، رنگش را می‌بینی.

The server returned status code 404, so the page does not exist.

سرور کد وضعیت 404 برگرداند، پس آن صفحه وجود ندارد.

از مستندات یک سرویس

Our service uses HTTPS for every call, so your data is safe.

To read data, send a GET request. A GET request has no body. To create something new, send a POST request and put the data in the body as JSON.

Every request needs a header with your token. The server always answers with a status code. Check the status code before you read the body: 200 means the request worked, and 404 means the page was not found.

سرویس ما برای هر فراخوانی از HTTPS استفاده می‌کند، پس داده‌ی تو امن است.

برای خواندن داده، یک درخواست GET بفرست. درخواست GET بدنه ندارد. برای ساختن چیز تازه، یک درخواست POST بفرست و داده را به شکل JSON در بدنه بگذار.

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