أعراف تصميم الـ API
في هذه الصفحة 8 موضوعات
نص الدروس والتمارين باللغة الإنجليزية، بينما تبقى واجهة الموقع وعناوين الدروس بالعربية.
نظرة عامة
الموضوعات
- DTOs
- التحويل (Mapping)
- أخطاء متسقة
- التصفية (Filtering)
- استراتيجيات الإصدارات (Versioning)
تعلّم أولًا
3 ساعة تدريب (تقدير)
مخرجات التعلم
- Map between entities and DTOs with plain code or a mapper library, and justify the choice.
- Apply consistent naming, date formats, money representation, and error shapes across endpoints.
- Implement filtering with query parameters.
- Compare API versioning strategies (URL, header, media type) and choose one.
الدروس
المختبر والتمارين
Lab
JNR-020-LAB1 · Shop API style guide
Outcomes: 1–4 · Time: ~3 h Write a one-page style guide covering naming, money, dates, enums, error shape, paging, filtering, and versioning (with your chosen strategy and reason). Bring every endpoint into compliance, and add filtering by category and price range to the product list.
Acceptance: no endpoint violates the guide.
Exercises (assessment: review an inconsistent API against the style guide)
| ID | Outcome | Task |
|---|---|---|
| JNR-020-EX01 | 1 | Write a from(...) mapper for Product to ProductResponse that hides an internal field. |
| JNR-020-EX02 | 1 | In five sentences, justify plain mapping code or MapStruct for the Shop API. |
| JNR-020-EX03 | 2 | Rewrite a response using price: 19.99, date: "03/04/26", status: 2 in the style guide's formats. |
| JNR-020-EX04 | 2 | Given three endpoints with different error shapes, define one shared error shape and apply it. |
| JNR-020-EX05 | 3 | Implement GET /products?category=&minPrice=&maxPrice= with all filters optional, and test the combinations. |
| JNR-020-EX06 | 4 | Compare URL, header, and media-type versioning in a table and choose one for Shop API. |
أظهر الحلول
- EX01
static ProductResponse from(Product p) { return new ProductResponse(p.getId(), p.getName(), p.getPriceCents()); } - EX02 Sample: small model and few mappings favor plain code (explicit, no extra dependency); many similar mappings favor MapStruct (generated, compile-time checked). Any justified choice is correct.
- EX03
"priceCents": 1999,"date": "2026-04-03T00:00:00Z","status": "SHIPPED". - EX04 e.g. the Problem Details shape (
type,title,status,detail); returned by one global handler. - EX05 Treat each null parameter as "no filter"; reject
minPrice > maxPricewith400. - EX06 URL versioning is the usual choice for simplicity and visibility; header and media-type keep URLs clean but are harder to test. Justification matters.
Outcome 2 (money, dates) is also checked by quiz Q05 to Q07.
الاختبار
Outcomes: O1 DTO mapping · O2 consistent formats · O3 filtering · O4 versioning.
اختبار ذاتي لك: لا توجد درجات، ولا يُحفظ أو يُرسل أي شيء. اختر إجابة ثم تحقق منها، ويمكنك المحاولة مرة أخرى كما تشاء.
الجزء العملي
Six exercises JNR-020-EX01 to EX06 plus the style-guide lab. Pass: at least five exercises, a style guide, and no endpoint violating it.
أخطاء شائعة
Money as floating point; local time without offset; breaking changes without a version.
التقييم
Review an inconsistent API against the style guide.
الصلة بالمسار الوظيفي
API governance (SRC-006, ARC-025).