Migration Gap Analysis (API V1 to API V2)

0 people liked this article

Overview

This section identifies functional and structural gaps between V1 (GraphQL) and V2 (REST).

It helps you:

Understand what changes in behavior and structure
Identify required code changes
Anticipate migration risks
Plan mitigation strategies

API V2 has feature parity at launch, but implementation patterns differ significantly.

Gap Categories

Each resource is evaluated across:

Category	Description
Structure	Response shape differences
Field Mapping	Naming and availability changes
Relationships	Nested vs flattened
Querying	Filtering, sorting, pagination
Operations	CRUD differences
Migration Impact	Required developer changes

Migration Resource Summary

Resource	Effort	Risk
Accounts	Low-Medium	🟡
Sites	Medium	🟡
Services	High	🔴
Cases	High	🔴

All Resources

Gap Summary

Category	V1 (GraphQL)	V2 (REST)	Impact
Structure	Nested / One Query	Flat / Multiple Endpoints	Increased orchestration
Pagination	Custom / Implicit	Standard (Offset, Limit)	Must implement consistent pagination logic across all endpoints
Filtering	Query Variables	Query Parameters	Need refactoring of all filtering logic

Resource: Account

Gap Summary

Category	V1 (GraphQL)	V2 (REST)	Impact
Structure	Nested (viewer.account)	Flat list (data[])	Medium
Field Selection	Flexible	Fixed	Low
Relationships	Implicit	Explicit via endpoints	Low

Key Gaps

❗Gaps

Gaps	GET: Retrieve Account Details
Nested Objects & Fields Removed
Fields Removed
Fields Renamed
Fields Added	legalName

➕ Enhancements

V1 (GraphQL)	V2 (REST)
Get only one specific account	Retrieve a list of all ‘Accessible Accounts’ Retrieve details for a specific account
	More fields added

Migration Action

Update response parsing
Implement pagination loop
Adjust the data access layer

Resource: Sites

Gap Summary

Category	V1 (GraphQL)	V2 (REST)	Impact
Structure	Nested	Standalone + Scoped Endpoints	Medium
Relationships	Inline	Flattened	Medium

Key Gaps

❗Gaps

Gaps	GET: Retrieve Account Details
Nested Objects & Fields Removed
Fields Removed
Fields Renamed	address → fullAddress
Fields Added	siteCode deliveryAccountName latitude longitude

➕ Enhancements

V1 (GraphQL)	V2 (REST)
Get sites for one specific account	Retrieve a list of all sites Retrieve details for a specific site
	More fields added

Migration Action

Replace nested queries with endpoint calls

Update data model for flattened relationships

Add filtering where needed

Resource: Services

Gap Summary

Category	V1 (GraphQL)	V2 (REST)	Impact
Data Model	Order Centric (ORD-)*	Service Centric (SVC-)*	High
Relationships	Deep Nesting	IDs + Partial Fields	High

Key Gaps

❗Gaps

Gaps	GET: Retrieve Account Details
Nested Objects & Fields Removed	Hardware brand cpeType lanIpAddress wanIpAddress IP Address ipAddress note subnetMask DNS primaryDns secondaryDns tertiaryDns
Fields Removed	technicalNotes plannedDeliveryDate readyForServiceDate requestedDeliveryDate serviceCategory
Fields Renamed	serviceName → name status: Values differ (Check schema in Swagger or download the OpenAPI Specification)
Fields Added	siteId siteName contractAccountId contractAccountName deliveryAccountName

➕ Enhancements

V1 (GraphQL)	V2 (REST)
Retrieve data for Orders (old order-centric data model with ORD- Ids)*	Retrieve data for Services (new service-centric data model with SVC- Ids)*
	Retrieve a list of all services Retrieve details for a specific service
	Consistent view of data as in expereoOne portal

Migration Action

Refactor data parsing logic
Introduce additional API calls if needed
Map renamed fields
Validate data completeness

Resource: Cases

Gap Summary

Category	V1 (GraphQL)	V2 (REST)	Impact
Operations	Mutation-based	REST verbs (POST/GET/PATCH)	High
Response (Create)	Returns full object	Returns ID only	High
Retrieval	Nested + array	Direct resource	Medium
Workflow	Single request	Multi-step	High

Key Gaps

❗Mutation → REST Workflow

V1: Create + return full object
V2: Create → then retrieve

❗Additional Calls Required

To retrieve case details: GET /v2/cases/{caseId}
To retrieve case messages: GET /v2//cases/{caseId}/caseMessages

❗Gaps: Create Case & Retrieve Case Details

Gaps	POST: Create Case	GET: Retrieve Case Details
Nested Objects & Fields Removed		Communication → Separate Endpoint message sentBy timestamp type Service deliveryAccount plannedDeliveryDate primaryDns readyForServiceDate requestedDeliveryDate secondaryDns serviceCategory serviceId serviceName status technicalNote tertiaryDns Site address city country deliveryAccount name siteId
Fields Removed	description	description
Fields Renamed	customerReference → customerCaseReference sentBy → creatorEmail	customerReference → customerCaseReference sentBy → creatorEmail
Fields Added		type creatorEmail siteId siteName serviceId serviceName contractAccountId contractAccountName deliveryAccountName

❗Gaps: Send and Retrieve Case Messages

Gaps	POST: Send Case Messages	GET: Retrieve Case Messages
Nested Objects & Fields Removed
Fields Removed
Fields Renamed	message → messageHtml customerReference → customerCaseReference sentBy → creatorEmail	message → messageText, messageHtml customerReference → customerCaseReference sentBy → creatorEmail
Fields Added		messageHtml

❗Gaps: Update Case Details

Gaps	PATCH: Update Case details
Nested Objects & Fields Removed
Fields Removed
Fields Renamed	customerReference → customerCaseReference
Fields Added	startOfTheIncident

➕ Enhancements

V1 (GraphQL)	V2 (REST)
One query to get a case details and all messages	Retrieve a list of all cases Retrieve details for a specific case Retrieve all messages for a specific case Text message HTML message
	Attachments Upload an attachment to a case message Retrieve all attachments for a specific case message Download the attachment
	Update the exact 'start of the incident' for the case

V1 (GraphQL)

V2 (REST)

One query to get a case details and all messages

Retrieve a list of all cases
Retrieve details for a specific case
Retrieve all messages for a specific case
- Text message
- HTML message

Attachments

Upload an attachment to a case message
Retrieve all attachments for a specific case message
Download the attachment

Update the exact 'start of the incident' for the case

Migration Actions

Split create + fetch logic
Update response handling
Add additional API calls for full case details and messages
Refactor workflows

Helpful Links

Migration Guide (API V1 to API V2)

What can we help you with?

Migration Gap Analysis (API V1 to API V2)

Overview

Gap Categories

Migration Resource Summary

All Resources

Gap Summary

Resource: Account

Gap Summary

Key Gaps

Migration Action

Resource: Sites

Gap Summary

Key Gaps

Migration Action

Resource: Services

Gap Summary

Key Gaps

Migration Action

Resource: Cases

Gap Summary

Key Gaps

Migration Actions

Popular Articles

What can we help you with?

Contact Us

Migration Gap Analysis (API V1 to API V2)

Overview

Gap Categories

Migration Resource Summary

All Resources

Gap Summary

Resource: Account

Gap Summary

Key Gaps

Migration Action

Resource: Sites

Gap Summary

Key Gaps

Migration Action

Resource: Services

Gap Summary

Key Gaps

Migration Action

Resource: Cases

Gap Summary

Key Gaps

Migration Actions

Related Articles

Popular Articles