انتقل إلى المحتوى
أمين أبوزيد
Englishالعربية
MID-062

تطور واجهات API

  • 6 درس
  • 2.5 ساعة تدريب (تقدير)
ابدأ الوحدة
في هذه الصفحة 8 موضوعات

نص الدروس والتمارين باللغة الإنجليزية، بينما تبقى واجهة الموقع وعناوين الدروس بالعربية.

نظرة عامة

الموضوعات

  • التوافق مع الإصدارات السابقة
  • تطور المخطط (schema evolution)
  • الإيقاف التدريجي (deprecation)

تعلّم أولًا

2.5 ساعة تدريب (تقدير)

مخرجات التعلم

  1. Classify changes to REST APIs and event schemas as compatible or breaking.
  2. Evolve event schemas with a schema registry and compatibility rules (Avro or Protobuf).
  3. Run a deprecation process: announce, measure usage, migrate consumers, remove.
  4. Apply the tolerant-reader principle in consumers.

الدروس

  1. 01ما الذي يُعد تغييرًا كاسرًا
  2. 02تطوير واجهات REST API
  3. 03سجلات المخططات (Schema registries) وأنماط التوافق
  4. 04القرّاء المتسامحون (Tolerant readers)
  5. 05الإيقاف التدريجي بالطريقة الصحيحة
  6. 06عرض عملي: تغيير OrderPlaced دون كسر المستهلكين

المختبر والتمارين

Lab

MID-062-LAB1 · Money format change

Outcomes: 1–4 · Time: ~2.5 h

  1. Classify the planned change (cents long to {amount, currency}) for the orders REST API and OrderPlaced.
  2. Release 1: add money beside total in both; register the new schema version; extend contract tests for old and new shapes.
  3. Migrate each consumer to money using a tolerant reader; track usage of total.
  4. Release 2: announce deprecation, wait for usage to reach zero, then remove total.

Acceptance: contract tests and schema registry pass at every step.

Exercises (assessment: change-classification quiz plus lab; five exercises)

IDOutcomeTask
MID-062-EX011Classify eight changes (add optional field, rename field, enum value added, status 200 to 201, cents to euros, new endpoint, optional param made required, longer max length) as compatible or breaking.
MID-062-EX022Write an Avro (or Protobuf) v2 of OrderPlaced adding currency and show it passes BACKWARD checks; then show a change that fails.
MID-062-EX032Explain when you upgrade producers first and when consumers first, for BACKWARD and FORWARD modes.
MID-062-EX044Make a consumer DTO tolerant: ignore unknown properties and handle an unknown enum value. Test it with an extended payload.
MID-062-EX053Write a deprecation plan for GET /orders?status= parameter values: announcement text, metric, dates, removal criteria.
أظهر الحلول
  • EX01 Compatible: add optional field, new endpoint, usually a new enum value only if consumers are tolerant. Breaking: rename, cents to euros (meaning), optional made required, tighter max length for existing inputs. 200 to 201 is breaking for strict clients; treat as breaking unless agreed.
  • EX02 Add {"name":"currency","type":"string","default":"EUR"}; passes. Removing a field without a default, or adding a field without a default, fails BACKWARD.
  • EX03 BACKWARD: new schema reads old data, so upgrade consumers first. FORWARD: old schema reads new data, so upgrade producers first. FULL allows either order.
  • EX04 @JsonIgnoreProperties(ignoreUnknown = true) (or mapper config) and map unknown enum values to an UNKNOWN default; the test deserializes an extra field and a new enum value.
  • EX05 Announce in changelog and Deprecation/Sunset headers; metric of calls per client; message clients; sunset date after the measured migration; remove when usage is zero or the date passed with owners informed.

الاختبار

Outcomes: O1 classify changes · O2 schema registry and compatibility · O3 deprecation process · O4 tolerant reader.

اختبار ذاتي لك: لا توجد درجات، ولا يُحفظ أو يُرسل أي شيء. اختر إجابة ثم تحقق منها، ويمكنك المحاولة مرة أخرى كما تشاء.

  1. 1Which change is usually compatible?O1
  2. 2Changing a price from cents to euros while keeping type long is:O1
  3. 3A consumer that rejects an unknown field is:O1
  4. 4BACKWARD compatibility means:O2
  5. 5In Avro, adding a field safely under BACKWARD needs:O2
  6. 6In Protobuf, a removed field's number should be:O2
  7. 7The correct order for retiring a field:O3
  8. 8Before removing a deprecated field you need:O3
  9. 9The tolerant-reader principle says:O4
  10. 10Versioning every change is a mistake because:O1

الجزء العملي

Five exercises MID-062-EX01 to EX05 plus the lab. Pass: classification quiz at 80% or better and a lab where contract tests and the registry pass at every step.

أخطاء شائعة

Removing fields in one release; versioning every change.

التقييم

Change-classification quiz plus lab.

الصلة بالمسار الوظيفي

API and data contracts (SRC-006) and event architecture (ARC-026).

اكتب للبحث في المستويات والمراحل والوحدات والدروس.