API چیست و بخش‌های یک سایت مدرن چطور با هم حرف می‌زنند؟

API مترادف REST، JSON یا یک فلش شبکه نیست

یک diagram ساده Browser → API → Database نشان می‌دهد و تیم کم‌کم آن را تعریف همه modern siteها فرض می‌کند. این shortcut بیش از حد چیزها را پنهان می‌کند. API یک interface/contract برای تعامل software است. بعضی APIها constructهای محلی Browser هستند. بعضی interfaceهای third-party از طریق network هستند. بعضی از HTTP استفاده می‌کنند، اما HTTP semantics به‌خودی‌خود REST، JSON، Database یا authorization model خاصی را اجبار نمی‌کند.

در این درس Modern Web Communication Flow Record v1 را می‌سازید: چه کسی چه چیزی را call می‌کند، interface چیست، invocation چگونه boundary را رد می‌کند، authority تصمیم دست چه کسی است، response چه چیزی را ثابت می‌کند، failure کجا ممکن است رخ دهد و چه چیزی هنوز unknown است.

Web path را استفاده کنید، ولی topology ثابت نسازید

WEBF-001 مرز Browser/Request/Response/resource را می‌دهد. WEBF-008 capability placement را می‌دهد تا Browser API و application responsibility با هم قاطی نشوند. این صفحه communication-flow slice مربوط به C01 chapter exit را می‌بندد اما API implementation، authentication، database design یا deployment lessonهای بعدی را پیش‌خور نمی‌کند.

قاعده اصلی: فقط hopی را رسم کنید که scenario واقعاً ثابت کرده است. server-rendered page می‌تواند initial data را بدون Browser API call جدا تحویل دهد. DOM یا Web Audio هم API هستند، حتی اگر remote REST service نباشند.

هر communication edge را به هفت سؤال بشکنید

1. Caller: کدام program/component operation را شروع می‌کند؟
2. Interface / contract: چه operation، input، output و error meaning expose شده؟
3. Invocation / transport: local call، Browser API، HTTP request، message، SDK call یا unknown؟
4. Target authority: کدام component واقعاً مالک data یا decision است؟
5. Input/request evidence: caller چه چیزی ارسال می‌کند؟
6. Output/response evidence: چه چیزی برمی‌گردد و دقیقاً چه چیزی را ثابت می‌کند؟
7. Failure/security boundary: transport، protocol، authentication، authorization، validation، business rule یا downstream dependency کجا می‌تواند fail شود؟

RFC 9110، HTTP را application-level request/response protocol تعریف می‌کند و client/server role را توضیح می‌دهد، اما API architecture خاصی را تحمیل نمی‌کند. [S-RFC9110]

MDN نیز نشان می‌دهد API الزاماً remote endpoint نیست: Browser APIها constructهایی هستند که Browser روی JavaScript در اختیار application می‌گذارد و third-party API category دیگری است. [S-MDN-API-INTRO]

برای هر interface یا hop یک row مستقل بسازید

Modern Web Communication Flow Record v1 حداقل این fieldها را داشته باشد:

caller، callee_or_provider، interface_name، contract_purpose، invocation_or_transport، request_or_input، response_or_output، authority_boundary، authentication_evidence، authorization_evidence، browser_sharing_or_cors_evidence، business_validity_evidence، failure_location، unknowns و next_evidence.

authentication، authorization، CORS و business success را merge نکنید. عبور از یک boundary، عبور از بقیه را ثابت نمی‌کند. 2xx درباره result در سطح HTTP semantics اطلاعات می‌دهد؛ به‌تنهایی اثبات نمی‌کند workflow کسب‌وکار کامل شده یا caller برای هر action downstream مجاز است.

Contract و transport می‌توانند مستقل تغییر کنند

API contract می‌گوید «چه operationی وجود دارد، چه inputی معتبر است، output/error چه معنایی دارد». transport می‌گوید «این invocation چگونه boundary را رد می‌کند». یک operation مفهومی ممکن است در یک architecture local library call باشد و در architecture دیگر HTTP interface. در مقابل، دو HTTP endpoint می‌توانند contractهای کاملاً متفاوت داشته باشند.

CORS هم باید محدود بماند. Fetch standard، CORS protocol را برای قواعد request/response sharing در Browser تعریف می‌کند. این با اثبات identity، authorization یا business permission یکی نیست. [S-FETCH-CORS]

همچنین Database را فقط وقتی رسم کنید که evidence وجود دارد. server ممکن است از memory، file، cache، service خارجی، computation یا چند downstream پاسخ دهد. اگر data path داخلی معلوم نیست، UNKNOWN ثبت کنید.

مثال حل‌شده: Browser preferences و settings service هم‌مبدأ

Browser UI settings page را باز می‌کند. JavaScript از Browser storage API یک draft محلی می‌خواند و سپس با HTTP درخواست ذخیره language را به settings service هم‌مبدأ می‌فرستد.

حداقل دو row داریم:

• Browser storage API: caller = page JavaScript؛ provider = Browser؛ invocation = local Browser API؛ خود API call network request را implied نمی‌کند.
• Settings service: caller = Browser application؛ provider = application service؛ transport = HTTP؛ request evidence = language update؛ response evidence = protocol/application response. اینکه Database وجود دارد یا نه unknown است تا server-side evidence داشته باشیم.

پس یک page می‌تواند هم local Browser API و هم network service API داشته باشد. API interface relationship است، نه transport ثابت.

Failure را در boundary واقعی diagnosis کنید

«response 200 است، پس order حتماً valid است.» HTTP success به‌تنهایی business invariant را ثابت نمی‌کند؛ application contract را بررسی کنید.

«CORS پاس شده، پس caller authorized است.» Browser response sharing با application authorization فرق دارد.

«API کند است، پس Database کند است.» latency ممکن است در validation، service دیگر، cache miss، computation، queue یا database باشد. hop مربوط به Database evidence می‌خواهد.

«API یعنی REST JSON.» Browser API، SDK/library interface، RPC-style service و HTTP resource interface همه می‌توانند API باشند؛ JSON و REST انتخاب‌های ممکن‌اند، نه تعریف.

برای برنامه‌نویس باتجربه: authority را روی diagram بنویسید

diagramهای معماری اغلب transport را نشان می‌دهند اما decision authority را نه. ستون authority اضافه کنید. componentی که session را authenticate می‌کند ممکن است مالک pricing نباشد. payment provider می‌تواند payment instrument را authorize کند ولی application شما مالک order-state transition باشد. Browser می‌تواند CORS sharing را enforce کند ولی server همچنان مالک application authorization است.

این تفکیک جلوی security theatre را می‌گیرد: network control جای business permission check نیست و disabled button در UI جای server-side authorization نیست. این درس implementation امنیت را آموزش نمی‌دهد؛ boundary contractها را جدا می‌کند.

Topology را بیش از حد استاندارد نکنید

Browser می‌تواند service را مستقیم call کند، data را داخل server-rendered HTML بگیرد یا از backend-for-frontend عبور کند. server می‌تواند external provider را مستقیم call کند یا از queue/worker استفاده کند. هر topology latency، coupling، security boundary، observability و failure mode متفاوتی دارد.

Record صحیح یک topology را برای همه پروژه‌ها ترجیح نمی‌دهد؛ بررسی می‌کند boundary انتخاب‌شده ownership و evidence را برای requirement فعلی واضح کرده یا نه.

فقط hopهای evidence‌شده را رسم کنید

Guided: page از fetch('/profile') استفاده می‌کند و server profile data برمی‌گرداند. هیچ چیز دیگری معلوم نیست. فقط Browser→service hop و HTTP evidence را ثبت کنید و storage server را UNKNOWN بگذارید.

Independent: page ابتدا navigator.geolocation را صدا می‌زند و بعد coordinate را به application service می‌فرستد. دو row بسازید. توضیح دهید چرا اولی Browser API و دومی network service interface است. permission، CORS، authentication و business validation را جدا نگه دارید.

Evidence bar

Record وقتی قابل دفاع است که:

• هر arrow caller و interface purpose دارد؛
• transport تعریف API نشده است؛
• HTTP success، CORS sharing، authentication، authorization و business correctness جدا هستند؛
• Database/service hop بدون evidence ساخته نشده؛
• server-rendered initial data بدون اجبار Browser API call جدا پذیرفته می‌شود؛
• failure به boundary قابل‌مشاهده متصل است؛
• unknown و next evidence صریح است.

Transfer بین Browser، application و external provider

transfer نهایی product UIای دارد که product data می‌گیرد و order submit می‌کند، و application server نیز external payment provider را call می‌کند. برای هر interface/hop row مستقل بسازید. caller، contract، transport، authority، request/response evidence، authentication/authorization evidence، CORS relevance، business-validity evidence، failure و unknown را مشخص کنید. Database را فقط در صورت evidence رسم کنید.

این task communication-flow chapter exit مربوط به C01 را با topology جدید می‌بندد.

Source boundary و freshness

RFC 9110 فقط HTTP request/response semantics را پشتیبانی می‌کند، نه REST architecture یا API design خاص. MDN abstraction API و Browser API exampleها را پشتیبانی می‌کند. Fetch standard مرز CORS/request/response sharing را پشتیبانی می‌کند. این sourceها authentication scheme، Database topology یا business authorization policy خاصی را ثابت نمی‌کنند. در review date، guidance evolving web platform را دوباره بررسی کنید بدون اینکه distinction پایدار contract، transport، authority و evidence را از بین ببرید.