داده، SQL، قراردادها و ماشین حالت · فصل ۵ — JSON Schema، OpenAPI، AsyncAPI، Protobuf و gRPC · 70
OpenAPI 3.1: HTTP Contract as Source
داده را ذخیره یا query می‌کند اما constraint، consistency، compatibility و recovery را به یک contract مهندسی تبدیل نمی‌کند. موضوع جاری: «OpenAPI 3.1: HTTP Contract as Source». می‌تواند «OpenAPI 3.1: HTTP Contract as Source» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
خلاصهٔ درس
داده را ذخیره یا query می‌کند اما constraint، consistency، compatibility و recovery را به یک contract مهندسی تبدیل نمی‌کند. موضوع جاری: «OpenAPI 3.1: HTTP Contract as Source».
می‌تواند «OpenAPI 3.1: HTTP Contract as Source» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
خروجی این درس
می‌تواند «OpenAPI 3.1: HTTP Contract as Source» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
پیش‌نیازها
_Locale: fa-IR · Lesson: DAT-013 · Public order: 70_
خروجی و artifact کاری
این درس برای ساختن رکورد بازبینی قرارداد HTTP در OpenAPI نسخه ۱ است: یک artifact تصمیم که مشاهده، فرض، محدودیت و evidence موردنیاز را از هم جدا می‌کند. هدف حفظ یک مدل قابل‌انتقال است، نه حفظ‌کردن نام ابزارها.
می‌تواند «OpenAPI 3.1: HTTP Contract as Source» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
مدل مرزی
OpenAPI می‌تواند source قابل بررسی قرارداد HTTP باشد، اما documentation زیبا evidence انطباق runtime نیست. review باید method/path، parameter، media type، schema درخواست و پاسخ، status outcome، example و رفتار مشاهده‌شده server را به هم وصل کند. نسخه document OpenAPI نیز باید از نسخه product API جدا بماند.
در هر بخش سه برچسب نگه دارید: «مشاهده‌شده»، «استنباط محدود» و «نیازمند بررسی». اگر evidence در دسترس نیست، نتیجه را unknown ثبت کنید؛ نام ابزار یا pass شدن یک happy path جای evidence را نمی‌گیرد.
1. Version fieldها سؤال‌های متفاوت دارند
مقدار top-level openapi نسخه specification مورد استفاده document را تعیین می‌کند؛ info.version نسخه API توصیف‌شده را طبق policy تیم مشخص می‌کند.
2. Operation فقط path نیست
method، path template، parameterهای path/query/header، request body، media type، response و security declaration با هم interface محدود را می‌سازند.
3. Schema Object مرز اعلام‌شده می‌خواهد
OpenAPI 3.1 مدل Schema Object را با vocabularyهای JSON Schema همسو می‌کند، اما پشتیبانی ابزار و dialect باید pin و test شود.
4. Example تزئین نیست
example درخواست باید با request schema و example پاسخ با status/media type/schema خود منطبق باشد. fixture منفی رفتار undocumented را آشکار می‌کند.
5. Runtime drift probe جدا می‌خواهد
document معتبر از نظر syntax می‌تواند با handler واقعی متفاوت باشد. contract test، request/response واقعی را مقایسه می‌کند بدون ادعای پوشش همه pathها.
روش پنج‌مرحله‌ای
- نسخه OAS را pin و rule مستقل نسخه API را ثبت کنید.
- یک operation را انتخاب و کل surface HTTP آن را فهرست کنید.
- example درخواست و پاسخ را با media type و Schema Object درست validate کنید.
- parameter required غایب، media type غلط، status undocumented و پاسخ schema-invalid را probe کنید.
- نتیجه document، مشاهده runtime، محدودیت tool و تصمیم compatibility را جدا ثبت کنید.
مثال حل‌شده
POST /orders بدنه JSON با customerId و حداقل یک item می‌پذیرد و outcomeهای 201، 400 و 409 را تعریف می‌کند. example baseline validate می‌شود و handler مصنوعی پاسخ 201 منطبق می‌دهد. probeها حذف customerId، ارسال text/plain، shape ثبت‌نشده 500 و header اختیاری آینده Idempotency-Key هستند. رکورد defect document را از drift handler جدا و اثر header اختیاری را مستقل از response جدید classify می‌کند.
ماتریس تصمیم و evidence
| موضوع | مرز/مالک | evidence | تصمیم یا محدودیت |
|---|---|---|---|
| نسخه document | openapi 3.1.x | pin source و parser | نسخه release API نیست |
| request | POST /orders application/json | example مثبت و منفی | fieldهای required enforce شدند |
| response | 201/400/409 | matrix status-media-schema | outcome ثبت‌نشده open می‌ماند |
| runtime | handler مصنوعی | exchange مشاهده‌شده | فقط evidence بخشی از pathها |
| تغییر | header اختیاری idempotency | review قدیم/جدید | تصمیم compatibility جدا |
خطاهای محتمل و روش اصلاح
- تلقی documentation تولیدشده به‌عنوان اثبات runtime
- یکی‌گرفتن openapi field با نسخه product API
- فرض رفتار یکسان همه code generatorها و validatorها
برای هر مورد، ادعا را محدود کنید، یک counterexample بسازید و بنویسید کدام مشاهده می‌تواند آن را تأیید یا رد کند.
تمرین انتقال
سناریو را طوری تغییر دهید که یکی از فرض‌های مثال دیگر برقرار نباشد. بدون کپی‌کردن تصمیم قبلی، رکورد بازبینی قرارداد HTTP در OpenAPI نسخه ۱ را دوباره بسازید؛ سپس تفاوت decision rule و تفاوت دادهٔ ورودی را توضیح دهید.
این درس چه چیزی را ثابت نمی‌کند
این درس certification، تضمین production یا پوشش همه implementationها را ادعا نمی‌کند. نتیجه فقط در مرز سناریو، sourceهای تاریخ‌دار و observationهای ثبت‌شده معتبر است.
خودسنجی
- [ ] آیا مسئولیت‌ها را از نام framework یا tool جدا کرده‌ام؟
- [ ] آیا دست‌کم یک failure probe و نتیجه موردانتظار آن را نوشته‌ام؟
- [ ] آیا fact، inference و design choice از هم مشخص‌اند؟
- [ ] آیا non-claim و evidence گمشده را ثبت کرده‌ام؟
- [ ] آیا transfer را روی context تغییرکرده و بدون پاسخ آماده انجام داده‌ام؟
منابع و مرز تازگی
sourceها در 2026-09-19 طبق Bible منجمدشده مرور شده‌اند. تاریخ review_due یک trigger برای بازبینی نسخه‌ای است؛ هیچ بسته‌ای نباید درجا و بدون نسخه جدید تغییر کند.
- OAS-3.1.2 — Normative OpenAPI 3.1 family semantics used by the locked lesson scope. (https://spec.openapis.org/oas/v3.1.2.html; review: 2026-10-17)
- OAS-LATEST — Current latest published OpenAPI Specification context; not used to rewrite the locked 3.1 lesson scope. (https://spec.openapis.org/oas/latest.html; review: 2026-10-17)
ارزیابی
پاسخ‌نامه‌ی این درس در بسته‌ی آموزش وجود ندارد؛ خودت جواب بده و صادقانه علامت بزن. «نیاز به مرور» درس را به صف تکرار می‌فرستد.
DAT-013-S1 retrieval
DAT-013-S2 application
DAT-013-S3 diagnosis
DAT-013-S4 decision
DAT-013-S5 transfer
ملاک‌های ارزیابی (rubric)
| Dimension | Critical | Sufficient evidence |
|---|---|---|
| contract/protocol correctness | yes | Explanation preserves version/dialect, compatibility/reliability and evidence semantics. |
| evidence quality | yes | Positive, negative and change/repair observations are traceable and separated from inference. |
| scope discipline | yes | Adjacent outcomes and unsupported tool/runtime generalizations are deferred. |
| transfer independence | yes | Changed-context task is solved without decisive scaffold. |
A submission passes only when every critical dimension is sufficient and the learner states missing evidence honestly. AI suggestions are not observed evidence; the learner remains accountable for the final bounded judgment.
منابع و تازگی
مطالعهٔ موارد (case studies)
فایل‌های آزمایشگاه
با fixture امن محلی، رکورد بازبینی قرارداد HTTP در OpenAPI نسخه ۱ را بسازید. ابتدا prediction را بنویسید؛ سپس baseline و failure probeهای اعلام‌شده را ثبت کنید و observation مثبت و منفی را نگه دارید. transfer را بدون کپی تصمیم مثال انجام دهید.
starter عمداً classification یا risk decision نهایی را انتخاب نمی‌کند. evaluate_record.py و evidence template را تکمیل کنید. اجرای python3 ../run_checks.py فقط environment و شکل fileها را بررسی می‌کند و تصمیم محتوایی شما را grade نمی‌کند.
مرز ایمنی: No production system/data, no external account/service dependency, and all failure probes must be bounded and deterministic.
رسانه و اسلایدهای درس
فایل‌های آموزشی (دانلود)