Skip to main content
maintainx-upgrade-migration Migrate MaintainX API versions and handle breaking changes.
Use when upgrading API versions, handling deprecations,
or migrating between MaintainX API releases.
Trigger with phrases like "maintainx upgrade", "maintainx api version",
"maintainx migration", "maintainx breaking changes", "maintainx deprecation".
Aller à l'installation Skills Marketplace Découvrez et explorez les compétences IA créées par la communauté.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Afficher les détails du prompt Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
npx skills add https://github.com/jeremylongshore/claude-code-plugins-plus-skills --skill maintainx-upgrade-migrationLa commande reste sur une seule ligne. Faites défiler horizontalement pour la vérifier avant de la copier.
Vous préférez une copie locale ? Téléchargez les fichiers actuellement disponibles dans SkillsMP.
Télécharger Zip Téléchargement... Métiers associés SOC
Basé sur la classification professionnelle SOC
Explorateur de fichiers
2 fichiers name maintainx-upgrade-migration description Migrate MaintainX API versions and handle breaking changes.
Use when upgrading API versions, handling deprecations,
or migrating between MaintainX API releases.
Trigger with phrases like "maintainx upgrade", "maintainx api version",
"maintainx migration", "maintainx breaking changes", "maintainx deprecation".
allowed-tools Read, Write, Edit, Bash(npm:*), Grep version 1.11.0 license MIT author Jeremy Longshore <jeremy@intentsolutions.io> tags ["saas","maintainx","api","migration"] compatibility Designed for Claude Code, also compatible with Codex and OpenClaw
MaintainX Upgrade & Migration
Current State
!npm list 2>/dev/null | head -20
Overview
Handle MaintainX API version upgrades, deprecations, and breaking changes with a safe, incremental migration strategy.
Prerequisites
Existing MaintainX integration
Test environment with separate API key
Version control (git) for all integration code
Instructions
Step 1: Audit Current API Usage
import { readFileSync, readdirSync, statSync } from 'fs' ;
import { join } from 'path' ;
function findApiCalls (dir : string Array <{ file : string ; line : number ; endpoint : string }> {
const results : Array <{ file : string ; line : number ; endpoint : string }> = [];
function scan (d : string for (const entry of readdirSync (d)) {
const full = join (d, entry);
if (statSync (full).isDirectory
if
startsWith
'.'
'node_modules'
scan
else
if
endsWith
'.ts'
endsWith
'.js'
const
readFileSync
'utf-8'
const
split
'\n'
for
let
0
length
const
match
/'"`[^'"`]*)/
if
push
file
line
1
endpoint
1
scan
return
const
findApiCalls
'./src'
console
log
'=== MaintainX API Usage Audit ==='
console
log
`Found ${calls.length} API calls:\n`
const
new
Map
string
typeof
for
const
of
const
endpoint
split
'?'
0
replace
/\/\d+/
'/:id'
const
get
push
set
for
const
of
console
log
`${endpoint} (${usages.length} calls):`
for
const
of
console
log
` ${u.file} :${u.line} `
Step 2: Version Compatibility Layer
type ApiVersion = 'v1' | 'v2' ;
interface VersionAdapter {
baseUrl : string ;
transformRequest (endpoint : string , data : any ): { endpoint : string ; data : any };
transformResponse (endpoint : string , data : any ): any ;
}
const adapters : Record <ApiVersion , VersionAdapter > = {
v1 : {
baseUrl : 'https://api.getmaintainx.com/v1' ,
transformRequest : (endpoint, data ) => ({ endpoint, data }),
transformResponse : (endpoint, data ) => data,
},
v2 : {
baseUrl : 'https://api.getmaintainx.com/v2' ,
transformRequest : (endpoint, data ) => {
if (endpoint.startsWith ('/workorders' ) && data) {
if (data.assignees ) {
data.assignedTo = data.assignees ;
delete data.assignees ;
}
}
return { endpoint, data };
},
transformResponse : (endpoint, data ) => {
if (data.assignedTo ) {
data.assignees = data.assignedTo ;
}
return data;
},
},
};
class VersionedClient {
private adapter : VersionAdapter ;
constructor (version : ApiVersion = 'v1' this .adapter = adapters[version];
}
async request (method : string , endpoint : string , data ?: any const { endpoint : ep, data : d } = this .adapter .transformRequest (endpoint, data);
const response = await fetch (`${this .adapter.baseUrl} ${ep} ` , {
method,
headers : {
Authorization : `Bearer ${process.env.MAINTAINX_API_KEY} ` ,
'Content-Type' : 'application/json' ,
},
body : d ? JSON .stringify (d) : undefined ,
});
const result = await response.json ();
return this .adapter .transformResponse (ep, result);
}
}
Step 3: Feature Flag Migration
const MIGRATION_FLAGS : Record <string , boolean > = {
USE_V2_WORKORDERS : false ,
USE_V2_ASSETS : false ,
USE_V2_PAGINATION : false ,
};
function getApiVersion (endpoint : string ApiVersion {
if (endpoint.startsWith ('/workorders' ) && MIGRATION_FLAGS .USE_V2_WORKORDERS ) return 'v2' ;
if (endpoint.startsWith ('/assets' ) && MIGRATION_FLAGS .USE_V2_ASSETS ) return 'v2' ;
return 'v1' ;
}
async function migratedRequest (method : string , endpoint : string , data ?: any const version = getApiVersion (endpoint);
const client = new VersionedClient (version);
return client.request (method, endpoint, data);
}
Step 4: Migration Tests
import { describe, it, expect } from 'vitest' ;
describe ('API Version Migration' , () => {
it ('v1 and v2 return equivalent work order data' , async () => {
const v1Client = new VersionedClient ('v1' );
const v2Client = new VersionedClient ('v2' );
const v1Result = await v1Client.request ('GET' , '/workorders?limit=5' );
const v2Result = await v2Client.request ('GET' , '/workorders?limit=5' );
expect (v1Result.workOrders .length ).toBe (v2Result.workOrders .length );
expect (v1Result.workOrders [0 ]).toHaveProperty ('id' );
expect (v1Result.workOrders [0 ]).toHaveProperty ('title' );
expect (v1Result.workOrders [0 ]).toHaveProperty ('status' );
});
it ('compatibility adapter transforms assignees correctly' , () => {
const adapter = adapters.v2 ;
const { data } = adapter.transformRequest ('/workorders' , {
title : 'Test' ,
assignees : [{ type : 'USER' , id : 1 }],
});
expect (data.assignedTo ).toBeDefined ();
expect (data.assignees ).toBeUndefined ();
});
});
Step 5: Rollback Procedure #!/bin/bash
echo "=== MaintainX API Version Rollback ==="
echo "1. Set all feature flags to false:"
echo ' MIGRATION_FLAGS.USE_V2_WORKORDERS = false'
echo ' MIGRATION_FLAGS.USE_V2_ASSETS = false'
echo ""
echo "2. Redeploy with v1 configuration:"
echo " git revert HEAD --no-edit && git push"
echo ""
echo "3. Verify v1 endpoints are working:"
echo ' curl -s https://api.getmaintainx.com/v1/workorders?limit=1 \'
echo ' -H "Authorization: Bearer $MAINTAINX_API_KEY" | jq .status'
echo ""
echo "4. Monitor error rates for 30 minutes"
echo "5. Document issues for v2 retry"
Output
API usage audit report listing all endpoints and call sites
Version compatibility layer with request/response adapters
Feature flag system for incremental per-endpoint migration
Migration tests verifying v1/v2 equivalence
Rollback procedure for safe revert
Error Handling Issue Cause Solution 404 on v2 endpoint Endpoint path changed Update adapter mappings Field missing in v2 response Breaking schema change Add field mapping in transformResponse Mixed v1/v2 data in DB Partial migration state Run reconciliation to normalize Feature flag stuck Config not reloaded Restart service or use dynamic config
Resources
Next Steps For CI/CD integration, see maintainx-ci-integration.
Examples Dual-write during migration (write to both v1 and v2):
async function dualWrite (endpoint : string , data : any const v1 = new VersionedClient ('v1' );
const v2 = new VersionedClient ('v2' );
const v1Result = await v1.request ('POST' , endpoint, data);
try {
await v2.request ('POST' , endpoint, data);
} catch (err) {
console .warn ('v2 write failed (non-blocking):' , err);
}
return v1Result;
}
