کلید و محدودیت
وقتی از API یک شرکت دیگر استفاده میکنی، کلید میگیری، سقف مصرف داری و ابزار آماده در اختیارت میگذارند. اینها کلمههای همان صفحهی «شروع کار» هستند.
never و always در هشدارها
مستندات برای قانونهای مهم از never (هیچوقت) و always (همیشه) استفاده میکنند و آنها را اول جملهی امری میگذارند: Never share your API key، Always use HTTPS. per هم یعنی «در هر»: 100 requests per minute یعنی صد درخواست در هر دقیقه.
هشت کلمهی این درس
API key (اِیپیآی کی): کلید API؛ رمزی که برنامهی تو را به سرویس میشناساند
key یعنی کلید. API key رشتهای بلند و تصادفی است که وقتی در یک سرویس ثبتنام میکنی به تو میدهند و برنامهات آن را با هر درخواست میفرستد. سرویس با آن میفهمد درخواست از طرف کدام مشتری است، چند بار صدایش زدهای و اجازهی چه کارهایی را داری. مثل کارت عضویت کتابخانه: بدون آن کتاب نمیدهند و هر چه بگیری به حساب تو نوشته میشود. فرقش با access token این است که کلید معمولاً مال برنامه است و عمرش طولانی؛ توکن مال یک کاربرِ واردشده است و زود باطل میشود.
Never commit your API key to a public repository.
هیچوقت کلید API خودت را در یک مخزن عمومی کامیت نکن.
secret (سیکرِت): راز؛ هر مقدار محرمانه مثل رمز و کلید
secret یعنی راز. برنامهنویسها به هر مقداری که نباید دست دیگران بیفتد secret میگویند: رمز پایگاه داده، API key، توکن، کلید رمزنگاری. قانون اول این است که secret هیچوقت داخل کد نوشته نمیشود و به گیت نمیرود؛ آن را در متغیر محیطی یا فایل .env میگذارند که در .gitignore آمده است. کد را میشود به همه نشان داد، راز را نه.
Keep the client secret on the server, never in the browser.
رمز کلاینت را روی سرور نگه دار، هیچوقت در مرورگر نگذار.
rate limit (رِیت لیمیت): سقف تعداد درخواست در یک بازهی زمانی
rate یعنی نرخ یا سرعت (چند تا در چه مدت) و limit یعنی حد. rate limit قانونی است که میگوید در یک بازهی زمانی حداکثر چند درخواست میتوانی بفرستی، مثلاً 60 درخواست در دقیقه. سرویسها این سقف را میگذارند تا یک برنامهی پرکار یا یک حمله، سرور را برای بقیه کند نکند. اگر از سقف رد شوی، جوابت کد 429 است.
The free plan has a rate limit of 60 requests per minute.
طرح رایگان سقف 60 درخواست در دقیقه دارد.
quota (کوئوتا): سهمیه؛ مقدار کل مجاز در یک دوره
quota یعنی سهمیه: مقداری که برای تو کنار گذاشتهاند. در سرویسهای آنلاین، quota کل مقداری است که در یک دورهی بلند (روز یا ماه) میتوانی مصرف کنی: هزار درخواست در ماه، پنج گیگابایت فضا. فرقش با rate limit این است که rate limit سرعت را محدود میکند (چند تا در دقیقه) و quota کل مقدار را (چند تا در ماه). مثل بستهی اینترنت گوشی: وقتی تمام شد، باید صبر کنی یا بستهی بزرگتر بخری.
You have used 90% of your monthly quota.
تو 90 درصد سهمیهی ماهانهات را مصرف کردهای.
webhook (وِبهوک): نشانیای که سرویس دیگر هنگام یک اتفاق خودش صدا میزند
hook یعنی قلاب. در حالت عادی تو از API میپرسی «خبر تازهای هست؟» و باید مدام بپرسی. webhook برعکس است: یک نشانی از سرور خودت را به آن سرویس میدهی و میگویی «هر وقت فلان اتفاق افتاد، خودت به این نشانی خبر بده». مثل این که بهجای هر ساعت زنگ زدن به پست، شمارهات را بدهی تا وقتی بسته رسید خودشان زنگ بزنند. مثلاً درگاه پرداخت وقتی پول واریز شد یک POST به webhook تو میفرستد، یا ربات پیامرسان هر پیام تازه را همینطور از سرور پیامرسان میگیرد.
Set up a webhook to get a message when a payment succeeds.
یک وبهوک راه بینداز تا وقتی پرداخت موفق شد پیام بگیری.
callback (کالبَک): تابعی که میدهی تا بعداً صدایش بزنند
call back در انگلیسی یعنی «بعداً خودم زنگ میزنم». callback تابعی است که خودت صدایش نمیزنی؛ آن را به یک تابع دیگر میدهی و میگویی «هر وقت کارت تمام شد یا فلان اتفاق افتاد، این را اجرا کن». مثل وقتی که شمارهات را به منشی میدهی تا هر وقت دکتر آزاد شد خبرت کند، و در این فاصله به کارهای دیگرت میرسی. در جاوااسکریپت همهجا هست: کلیک دکمه، تایمر، جواب سرور.
Pass a callback that runs when the download finishes.
یک کالبک بده که وقتی دانلود تمام شد اجرا شود.
SDK (اِسدیکِی): بستهی آمادهی ابزار و کد برای کار با یک سرویس
kit یعنی جعبهابزار یا بستهای که همهی وسایل یک کار در آن است. SDK بستهای است که یک شرکت میدهد تا کار با سرویسش آسان شود: کتابخانهی آماده، نمونهکد، مستندات و گاهی ابزار تست. بدون SDK باید خودت درخواست HTTP بسازی، هدر بگذاری و JSON را باز کنی؛ با SDK یک تابع را صدا میزنی و بقیه را خودش انجام میدهد. مثل فرق کیک پختن از صفر با پودر کیک آماده. پس API خودِ در است و SDK دستگیرهی راحتی که برای زبان تو رویش گذاشتهاند.
Install the Python SDK to use the API with less code.
SDK پایتون را نصب کن تا با کد کمتری از API استفاده کنی.
sandbox (سَندباکس): محیط آزمایشی و جدا، بدون خطر برای چیزهای واقعی
sandbox یعنی جعبهی شن: همان جعبهای که بچهها در پارک در آن شنبازی میکنند و هر چه بسازند و خراب کنند، بیرون جعبه چیزی به هم نمیریزد. در برنامهنویسی، sandbox محیطی جدا و امن است برای امتحان کردن. خیلی از APIها یک نسخهی sandbox دارند: همان شکل و همان اندپوینتها، ولی با داده و پول غیرواقعی؛ میتوانی پرداخت آزمایشی بفرستی بی آن که ریالی جابهجا شود. معنی دومش زندانی کردن یک برنامه است تا به بقیهی سیستم دست نزند، مثل هر تب مرورگر.
Test your payment code in the sandbox before going live.
قبل از انتشار، کد پرداختت را در محیط سندباکس تست کن.
قدمهای اول
Getting started
1. Create an API key in your dashboard. The key is a secret: never put it in your frontend code.
2. Install our Python SDK. It is easier than writing every request yourself.
3. Use the sandbox first. In the sandbox, no real money moves.
4. Set a webhook URL. We will call it when a payment is done.
The free plan has a rate limit of 100 requests per minute and a quota of 10,000 requests per month.
شروع کار
۱. در داشبوردت یک کلید API بساز. این کلید یک راز است: هیچوقت آن را در کد فرانتاند نگذار.
۲. SDK پایتون ما را نصب کن. از این که هر درخواست را خودت بنویسی آسانتر است.
۳. اول از سندباکس استفاده کن. در سندباکس هیچ پول واقعی جابهجا نمیشود.
۴. یک نشانی وبهوک تعیین کن. وقتی پرداختی انجام شد، آن را صدا میزنیم.
طرح رایگان سقف 100 درخواست در دقیقه و سهمیهی 10,000 درخواست در ماه دارد.