⚠️ API V1 will sunset and will no longer be available after the deadline.

Feature Parity

API V2 has full feature parity with V1.

However:

• Some features may be 
  • structured differently; flattened instead of nested
• Some fields may be:
  • Removed
  • Renamed
  • Moved to different endpoints
• Some data may be:
  • Flattened
  • Returned via different endpoints
  • Retrieved via multiple calls

Migration Approach

Step 1: Inventory Current Usage

• Identify all GraphQL queries
• Group by resource:
  • Accounts
  • Sites
  • Services
  • Cases

Step 2: Map to REST Endpoints

Example:

What This Means in Practice

• In V1 (GraphQL)

You request exactly what you need:

query {
  viewer {
    account {
      sites {
        siteId
        name
        city
      }
    }
  }
}

• In V2 (REST)

You call a dedicated endpoint:

GET /v2/sites

• Then refine using:
  • Query parameters
  • Filtering
  • Pagination

Step 3: Implement V2 Calls

• Replace queries with REST endpoints
• Add pagination handling
• Add filtering where needed

Step 4: Validate Data Consistency

• Compare V1 vs V2 responses
• Validate:
  • Field values
  • Record counts
  • Edge cases

Step 5: Rollout Gradually

• Start with non-critical workflows
• Expand coverage
• Monitor errors and performance

Important Migration Consideration

Structural Differences

• GraphQL: nested responses
• REST: flattened resource objects

Multiple Calls Instead of One

• GraphQL → single query
• REST → multiple endpoint calls

Explicit Data Retrieval

• REST requires explicit endpoint selection
• Use filters to optimize responses

Pagination Is Mandatory

• Large datasets are always paginated

Validation & Testing Guidance

Compare Responses

• Ensure parity between V1 and V2 data
• Pay attention to:
  • Field naming differences
  • Structure changes
  • Deprecated fields

Test Pagination

• Validate full dataset retrieval
• Ensure no missing records

Test Filtering & Sorting

• Confirm results match expectations

Test Error Handling

• Validate behavior for:
  • Invalid IDs
  • Unauthorized access
  • Missing parameters

Best Practices

Use Pagination for Large Datasets

• Default limit: 25
• Maximum limit: 200
• Use: ?page[offset]=0&page[limit]=25

Use Filtering to Reduce Payload Size

• Example: /v2/accounts?filter[Name]=ACME Corporation

Use Sorting for Predictable Results

• Example: /v2/accounts?sort=AccountId,-Name

Handle Pagination via Links

• Use the links.next field instead of manually constructing URLs.

Implement Robust Error Handling

Expect standard HTTP status codes:

• 200: Success
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 422: Validation Failure

Prepare for Future Evolution

• Avoid hardcoding assumptions about response structure
• Always use documented fields
• Plan for new fields to be added