Integration & APIsAPIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. evolution is a documentation-heavy, detail-oriented process. AI can accelerate parts of it significantly, especially the tedious parts like comparing schemas, drafting migrationWhat is migration?A versioned script that changes your database structure (add a column, create a table) so every developer and server stays in sync. guides, and reviewing diffs for compatibility. But it also has blind spots that can cause real production incidents if you trust it blindly.
What AI does well vs poorly
| Task | AI effectiveness | Why |
|---|---|---|
| Detecting removed/renamed fields in a diff | High | Structural comparison is straightforward |
| Generating migration guide drafts | High | Pattern-based writing AI excels at |
| Listing all fields that changed type | High | Schema comparison is mechanical |
| Reviewing OpenAPI spec diffs | High | Well-defined format, clear rules |
| Detecting optional-to-required changes | Medium | Requires understanding validation context |
| Identifying semantic behavior changes | Low | AI cannot infer runtime behavior from code alone |
| Knowing which consumers will be affected | Low | AI has no visibility into consumer codebases |
| Evaluating business impact of a break | Low | Requires organizational context AI does not have |
| Detecting timing/ordering changes | Low | Subtle behavioral change, not visible in schemas |
| Assessing migration effort for consumers | Low | Depends on consumer architecture AI cannot see |
email to contactEmail breaks not just the API call but every local database record and cached object on every phone. Always have the consumer team review the migration guide before publishing.Prompt template: analyzing breaking changes in a diffWhat is diff?A comparison showing exactly which lines were added, removed, or changed between two versions of code.
When you have an APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. change and want to check for breaking changes, give AI the before and after schemas:
You are an API compatibility reviewer. I am changing my API and need you
to identify every breaking change between v1 and v2.
A breaking change is anything that would cause an existing consumer
to fail without modifying their code. This includes:
- Removed fields
- Renamed fields
- Changed field types
- Fields changed from optional to required
- Removed or renamed endpoints
- Changed enum values (removed values)
- Changed default values or sort orders
- Changed error response formats
V1 schema:
[paste your current OpenAPI spec or response example]
V2 schema:
[paste your proposed OpenAPI spec or response example]
For each breaking change found:
1. Describe what changed
2. Explain why it breaks existing consumers
3. Suggest a non-breaking alternative if possiblePrompt template: generating a migrationWhat is migration?A versioned script that changes your database structure (add a column, create a table) so every developer and server stays in sync. guide
Generate a migration guide for API consumers upgrading from v1 to v2.
V1 endpoint: GET /v1/users/:id
V1 response:
{
"id": 123,
"name": "Alice Smith",
"email": "alice@example.com",
"role": "admin"
}
V2 endpoint: GET /v2/users/:id
V2 response:
{
"id": 123,
"firstName": "Alice",
"lastName": "Smith",
"contactEmail": "alice@example.com",
"role": "administrator",
"profile": { "avatar": null, "bio": null }
}
The guide should include:
1. A summary of all changes
2. A field-by-field mapping table (old -> new)
3. Code examples showing before and after for JavaScript consumers
4. A list of potential gotchasPrompt template: reviewing APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. compatibility
Review this pull request diff for API compatibility issues. The API
is consumed by mobile apps (iOS and Android) and three third-party
integrations.
[paste diff]
Check for:
- Any response field removals or renames
- Request validation changes (new required fields)
- Status code changes
- Error format changes
- Header changes
- Behavioral changes (sort order, pagination, defaults)
Rate each issue as: BREAKING, POSSIBLY BREAKING, or SAFE.What to verify manually
AI will miss these. Always check them yourself.
Optional-to-required field changes. AI often marks these as "minor" because the field already existed. But if a consumer never sent that field because it was optional, their requests now fail with 400 errors.
Semantic behavior changes. If your endpointWhat is endpoint?A specific URL path on a server that handles a particular type of request, like GET /api/users. used to return users sorted by creation date and now returns them sorted by name, that is a breaking changeWhat is breaking change?A modification to an API that causes existing code using it to stop working, such as renaming a field or changing a response format.. AI reading the code might not flag it because the response schemaWhat is schema?A formal definition of the structure your data must follow - which fields exist, what types they have, and which are required. did not change, only the ordering did.
Type widening that narrows in practice. Changing a field from number to string | number looks additive. But if consumer code does if (user.id === 123) (strict equality), the string "123" will not match. AI often misses this because the schema technically expanded.
Rate limit changes. Lowering rate limits from 1000/min to 100/min is a breaking change for high-traffic consumers. AI has no way to know your consumers' traffic patterns.
AuthenticationWhat is authentication?Verifying who a user is, typically through credentials like a password or token. changes. Switching from APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. key to OAuthWhat is oauth?An authorization protocol that lets users grant a third-party app limited access to their account on another service without sharing their password., or adding a required scopeWhat is scope?The area of your code where a variable is accessible; variables declared inside a function or block are invisible outside it., breaks every existing consumer. AI might classify this as a "configuration change" rather than a breaking change.
Hybrid workflow
Here is how to combine AI and human judgment effectively:
- Before the PR: Ask AI to review your schemaWhat is schema?A formal definition of the structure your data must follow - which fields exist, what types they have, and which are required. diffWhat is diff?A comparison showing exactly which lines were added, removed, or changed between two versions of code. for breaking changes. Use the first prompt template above.
- During review: Read AI's analysis, then check for the subtle issues it misses (behavior changes, auth changes, timing).
- After approval: Ask AI to draft the migrationWhat is migration?A versioned script that changes your database structure (add a column, create a table) so every developer and server stays in sync. guide using the second template. Edit for accuracy and add consumer-specific notes.
- Before deployment: Run contract tests (Pact) against actual consumer expectations, this is the ground truth, not AI analysis.
- After deployment: Monitor deprecated endpointWhat is endpoint?A specific URL path on a server that handles a particular type of request, like GET /api/users. metrics. Ask AI to summarize usage trends from your metrics data.
The pattern is consistent: AI drafts, humans verify, automated tests confirm. AI saves you from the blank page problem and catches mechanical issues. Humans catch the subtle, contextual issues that matter most. Contract tests catch everything that both missed.