94.8%
6
2.4h
| API | From | To | Difficulty | Est. Time | Breaking Changes |
|---|---|---|---|---|---|
| Bookings API | v1.5 | v2.0 | Medium | 2-4 hours | 8 |
| Events API | v1.0 | v2.1 | Easy | 1-2 hours | 2 |
| Venues API | v1.2 | v1.8 | Easy | 30 min | 0 (additive) |
| Auth API | v1.x | v2.5 | Hard | 4-8 hours | 15 |
| Search API | v1.x | v2.4 | Medium | 2-3 hours | 5 |
| Notify API | v1.0 | v2.0 | Easy | 1 hour | 3 |
Review breaking changes list for target version
Update SDK package to latest compatible version
Update API endpoint URLs with new version prefix
Update request/response DTOs for renamed or removed fields
Test all affected endpoints in staging environment
Monitor error rates after deployment for 24 hours
Remove deprecated API calls from codebase
| Change | v1.5 (Old) | v2.0 (New) | Action |
|---|---|---|---|
| Booking creation | POST /booking/v1/bookings | POST /booking/v2/bookings | Update URL |
| Price field | price: number | pricing: { base, tax, total } | Update DTO |
| Group booking | Not supported | POST /booking/v2/groups | New endpoint |
| Status enum | pending|confirmed|cancelled | draft|pending|confirmed|completed|cancelled | Update enum |
| Attendee field | attendeeEmail: string | attendee: { email, name, phone } | Restructure |
| Pagination | page/limit | cursor/limit | Update pagination |
| Response envelope | { data: [...] } | { data: [...], page: {}, meta: {} } | Update parsing |
| Idempotency | Not supported | Idempotency-Key header required for POST | Add header |
// BEFORE: Bookings API v1.5
import { BookingClient } from '@eventzr/booking-client';
const client = new BookingClient({ baseUrl: API_URL, tenantId });
const booking = await client.createBooking({
eventId: 'evt_123',
attendeeEmail: 'user@example.com',
price: 49.99,
});
// AFTER: Bookings API v2.0
import { BookingClient } from '@eventzr/booking-client'; // v2.1.0+
const client = new BookingClient({ baseUrl: API_URL, tenantId });
const booking = await client.create({
eventId: 'evt_123',
attendee: {
email: 'user@example.com',
name: 'John Doe',
},
pricing: {
base: 49.99,
currency: 'USD',
},
}, {
headers: { 'Idempotency-Key': crypto.randomUUID() }
});Use the migration testing endpoint to validate your integration against the new API version without affecting production data.
// Dry-run mode: Validate requests against v2.0 schema
// without actually creating resources
POST /booking/v2/bookings?dry_run=true
Authorization: Bearer <token>
x-tenant-id: <tenant-id>
Content-Type: application/json
{
"eventId": "evt_123",
"attendee": { "email": "user@example.com", "name": "Test" },
"pricing": { "base": 49.99, "currency": "USD" }
}
// Response: 200 OK with validation result
{
"data": { "valid": true, "warnings": [] },
"meta": { "api_version": "v2.0", "dry_run": true }
}Need help migrating? Enterprise customers get dedicated migration support. Contact support@eventzr.com or submit a migration assistance request via the developer dashboard. Average response time: 4 hours.