Migration Guide from Version 1 to Version 2
We understand the importance of a seamless transition to the latest version of our API. To assist you in this process, we have prepared a comprehensive migration guide that provides step-by-step instructions on how to upgrade your existing integrations for using the new APIs.
URL changes
The endpoints have been updated to their newest versions as follows:
Deprecation notice and timelines
To ensure a smooth transition, we will continue supporting Version 1 of our API until 24 Sep 2024. However, we strongly encourage all developers to migrate to Version 2 as soon as possible to take advantage of the latest enhancements. The deprecation timeline is as follows:
- Deprecation Date: On 24 Sep 2024, the previous version will be officially deprecated. This is the official date of the new service, and the old service will move into maintenance mode only.
Note: No new features will be added to this version.
- End of Support Date: 24 Mar 2025 support for the previous version will cease. Please migrate any current apps using the prior version as soon as possible. Reach out to our support group if you have any problems.
List of changes
Following are the changes and the steps required to transition from Version 1 to Version 2.
Change 1: The type of all input IDs has been changed
Applicable Breaking Changes:
- The data type for all input IDs has been updated from String to ID.
Migration Steps:
- For all queries, adjust the data type of the input variable from String to ID.
Before:
query GetHub($hubId: String!) {
hub(hubId: $hubId) {
id
name
}
}
After:
query GetHub($hubId: ID!) {
hub(hubId: $hubId) {
id
name
}
}
Change 2: The structure of having a single root folder is no longer applicable
Applicable Breaking Changes:
The structure of having just one root folder is no longer in effect. You can now include multiple folders and items directly within a project. In order to support this new folder structure, we’ve made the following changes:
- The
Project.rootFolder
field has been removed. - A new field,
Project.items
, has been added.
Migration Steps:
- Upon accessing the project, you will be able to fetch all the folders and items contained within that specific project.
Before:
query GetProject($projectId: String!) {
project(projectId: $projectId) {
id
name
rootFolder {
id
name
}
}
}
After:
query GetProject($projectId: ID!) {
project(projectId: $projectId) {
id
name
hub {
id
name
}
folders {
results {
id
name
objectCount
items {
results {
id
name
__typename
}
}
}
}
}
}
Change 3: Folder is no longer considered an item
Applicable Breaking Changes:
- Folder is no longer considered an item, and is not returned as part of the items queries.
Migration Steps:
- To access folders use the dedicated folder and folders queries instead.
Before:
query GetFolderItem($projectId: String!,
$folderId: String!) {
item(projectId: $projectId, itemId: $folderId) {
id
name
… on Folder {
objectCount
}
}
}
After:
query GetFolderByHubId($hubId: ID!, $folderId: ID!) {
folderByHubId(hubId: $hubId, folderId: $folderId) {
FolderByHubId Fields
}
}
Change 4: Component no longer implements item
Applicable Breaking Changes:
- Component no longer implements item. Adjust all items queries to expect
DesignItem
instead ofcomponent
. DesignItem
andDesignItemVersion
types have been added.DesignFile
andDesignFileVersion
types have been removed.
Migration Steps:
- To migrate, adjust all items queries to expect
DesignItem
instead ofcomponent
. - You can go from a
DesignItem
to aComponentVersion
by using thetipRootComponentVersion
field.
Before:
query GetComponentItem($projectId: String!, $componentId: String!) {
item(projectId: $projectId, itemId: $componentId) {
id name … on Component {
tipVersion {
id
name
}
}
}
}
After:
query GetItemById($projectId: ID!, $itemId: ID!) {
item(projectId: $projectId, itemId: $itemId) {
id
name
createdOn
createdBy {
id
userName
}
lastModifiedOn
lastModifiedBy {
id
userName
}
project {
id
name
}
... on DesignItem {
id
name
rootComponent {
id
name
tipVersion {
id
name
}
}
}
... on DrawingItem {
id
name
tipVersion {
id
name
}
}
}
}
Change 5: Drawing no longer implements items
Applicable Breaking Changes:
- Drawing no longer implements items. Adjust all items queries to expect
DrawingItem
instead ofDrawing
. DrawingItem
andDrawingItemVersion
types have been added.DrawingFile
andDrawingFileVersion
types have been removed.
Migration Steps:
- To migrate, adjust all items queries to expect
DrawingItem
instead ofDrawing
. - You can go from a
DrawingItem
to aDrawingVersion
by using thetipDrawing
field.
Before:
query GetDrawingItem($projectId: String!, $drawingId: String!) {
item(projectId: $projectId, itemId: $drawingId) {
id
name
... on Drawing {
tipVersion {
id
name
}
}
}
}
After:
query GetDrawing($drawingId: ID!) {
drawing(drawingId: $drawingId) {
id
name
tipVersion {
id
name
componentVersion {
id
name
}
drawingItemVersion {
id
name
}
}
}
}
Change 6: All Manage extension (ME) fields are now grouped under a manage field
Applicable Breaking Changes:
- All Manage extension (ME) fields are now grouped under a manage field.
Migration Steps:
- To migrate, adjust your queries to use the ME fields under manage.
Before:
query GetComponentVersion($componentVersionId: String!) {
componentVersion(componentVersionId: $componentVersionId) {
lifeCycle
isLocked
isNextReleaseMilestone
revision
changeOrder
changeOrderURN
changeOrderURL
releasedOn
}
}
After:
query GetManageExtensionDetails($componentVersionId: ID!) {
componentVersion (componentVersionId: $componentVersionId) {
id
name
manage {
changeOrder
changeOrderURL
changeOrderURN
isLocked
isNextReleaseMilestone
itemNumber
lifeCycle
releasedOn
revision
}
component {
manage {
lifeCycle
revision
itemNumber
itemURN
itemURL
}
}
}
}
Change 7: The itemId
argument of the items query was renamed to folderId
Applicable Breaking Changes:
- The
itemId
argument of the items query is renamed tofolderId
.
Migration Steps:
- To migrate, rename
itemId
tofolderId
.
Before:
query GetItems($projectId: String!, $folderId: String!) {
items(projectId: $projectId, itemId: $folderId) {
results {
id
name
}
}
}
After:
query GetFolderItemsByFolder($projectId: ID!, $folderId: ID!, $filter: ItemFilterInput) {
itemsByFolder(projectId: $projectId, folderId: $folderId, filter: $filter) {
results {
__typename
id
name
}
}
}
Change 8: The Item query has been refactored to accept hubId
instead of projectId
.
Applicable Breaking Changes:
The Item query is refactored to accept hubId
instead of projectId
.
Migration Steps:
- To migrate, replace
projectId
withhubId
.
Before:
query Getltem($projectId: String!, $itemId: String!) {
item(projectId: $projectId, itemId: $itemId) {
name
}
}
After:
query GetItemById($hubId: ID!, $itemId: ID!) {
item(hubId: $hubId, itemId: $itemId) {
id
name
createdOn
lastModifiedOn
project {
id
name
}
... on DesignItem {
id
name
rootComponent {
id
name
tipVersion {
id
name
}
}
}
... on DrawingItem {
id
name
tipVersion {
id
name
}
}
}
}
Change 9: Changes were made regarding extensionType
Applicable Breaking Changes:
- Remove Folder.extensionType
- Remove ItemFilterInput.extensionType
- Add ItemFilterInput.itemType that accepts a ItemTypeEnum with possible values:
- DESIGN_ITEM
- DRAWING_ITEM
Migration Steps:
- To migrate, filter items by
itemType
instead.
Before:
query GetItems($projectId: String!, $folderId: String!) {
items(projectId: $projectId, itemId: $folderId) {
results {
id
name
}
}
}
After:
query GetFolderItemsByProject($projectId: ID!, $filter: ItemFilterInput) {
itemsByProject(projectId: $projectId, filter: $filter) {
results {
__typename
id
name
}
}
}
Change 10: End of support for the API based URL for generating thumbnail
Applicable Breaking Changes:
- End of support for the API based URL for generating thumbnail.
Migration Steps:
- To migrate, use CDN based URL for generating thumbnail.
Before:
query GetComponentVersion($componentVersionId: String!) {
componentVersion (componentVersionId: $componentVersionId) {
id
name
partNumber
isMilestone
materialName
lastModifiedOn
thumbnail {
id
progress
status
smallImageUrl
mediumImageUrl
largeImageUrl
}
}
}
After:
query GetComponentVersion($componentVersionId: ID!) {
componentVersion(componentVersionId: $componentVersionId) {
id
name
partNumber
partDescription
designItemVersion {
id
name
extensionType
}
thumbnail {
status
signedUrl
}
component {
id
name
}
}
}