Overview
Migrate the concrete resource and operation named by provider evidence. Procore does not expose one universal pack-wide version transition, so never claim a generic v1-to-v1.1 upgrade without endpoint-specific documentation.
Prerequisites
- Deprecated route, method, version, or payload format and documented replacement
- API Call Activity Report slice covering every deployed caller
- Old and new response contracts, test fixtures, rollout owner, and removal deadline
Instructions
Step 1: Prove affected traffic
Find the normalized deprecated route in production activity and search every service, scheduled job, event handler, and shared adapter for callers.
Step 2: Diff contracts
Compare paths, headers, IDs, query parameters, request fields, response fields, pagination, permissions, status codes, webhook schema, and lifecycle phase.
Step 3: Build a compatibility adapter
Isolate the new contract behind a resource-specific interface. Normalize only fields the business layer truly needs and preserve provider errors and metadata.
Step 4: Verify side by side
For reads, compare sanitized result sets and state hashes. For writes, use sandbox fixtures or a provider-supported idempotent strategy; do not duplicate live mutations.
Step 5: Roll out by cohort
Canary the new adapter, monitor error and rate signals, and keep an explicit rollback boundary while the old route remains supported.
Step 6: Remove the old path
After traffic evidence reaches zero and the observation clears, remove compatibility code, fixtures, configuration, and documentation for the deprecated contract.
Authentication
Both contracts use the intended OAuth 2.0 principal and company boundary. A migration must not widen DMSA permissions or switch grant types unless that separate security change is reviewed.
Tool Discipline
Use Read and Grep to inspect changelogs, activity reports, adapters, and callers. Use Write or Edit only for the approved adapter, migration test, rollout configuration, or receipt; do not perform duplicate live writes.
Output
- Provider evidence and complete caller inventory
- Contract diff, compatibility adapter, and equivalence tests
- Canary, rollback, zero-traffic, and removal receipt
Return the exact old and new contracts, affected volume, semantic differences, rollout status, and deletion evidence.
Examples
A deprecated webhook route is still called by one monthly job. The team adds the documented scoped replacement, verifies payload and permission differences, canaries it, and removes the legacy route only after the API activity report shows no callers.
Error Handling
| Failure | Response |
|---|---|
| Replacement is not documented | Stop and contact Procore API support rather than guessing a private route. |
| Read results diverge | Classify each delta and delay cutover until expected differences are approved. |
| New contract needs more permission | Review the manifest change separately and rerun negative-access tests. |
| Old traffic persists | Find the remaining caller; do not delete compatibility code. |