Rehearse API Contract Migrations in Daytona

authors/thefinalmilkman.md

@@ -0,0 +1,13 @@
+Author: The Final Milkman
+Title: Software Developer
+Description: The Final Milkman is a software developer focused on practical
+  automation, developer tooling, and verifiable AI-assisted workflows. He
+  enjoys turning ambiguous engineering tasks into small systems that can be
+  tested, reviewed, and improved.
+Author Image: [https://avatars.githubusercontent.com/thefinalmilkman?size=512]
+Author LinkedIn:
+Author Twitter:
+Company Name:
+Company Description:
+Company Logo Dark:
+Company Logo White:

definitions/20260603_definition_api_contract_migration.md

@@ -0,0 +1,28 @@
+---
+title: 'API Contract Migration'
+description:
+  'An API contract migration changes a request or response shape while managing
+  compatibility for existing consumers.'
+date: 2026-06-03
+author: 'The Final Milkman'
+---
+
+# API Contract Migration
+
+## Definition
+
+An API contract migration is a planned change to the structure or behavior of
+an API request, response, error, or event. The migration defines the new
+contract and the steps required to keep existing consumers working while they
+adopt it.
+
+## Context and Usage
+
+API contract migrations are common when a service renames fields, nests data,
+adds version metadata, changes validation rules, or retires legacy behavior. A
+safe migration usually includes a compatibility window, automated contract
+tests, consumer updates, and a separate removal step for deprecated fields.
+
+For example, an API can introduce `profile.display_name` while temporarily
+preserving a legacy top-level `name` field. New consumers can adopt the nested
+field without immediately breaking older clients.