Request

Response

    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
       }
     }
    }
    
    Show More

    After:

    query GetProject($projectId: ID!) {
        project(projectId: $projectId) {
            id
            name
            hub {
                id
                name
            }
            folders {
                results {
                    id
                    name
                    objectCount
                    items {
                        results {
                            id
                            name
                            __typename
                        }
                    }
                }
            }
        }
    }
    
    Show More

    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
    
       }
    
      }
    
    }
    
    Show More

    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 of component.
    • DesignItem and DesignItemVersion types have been added.
    • DesignFile and DesignFileVersion types have been removed.

    Migration Steps:

    • To migrate, adjust all items queries to expect DesignItem instead of component.
    • You can go from a DesignItem to a ComponentVersion by using the tipRootComponentVersion field.

    Before:

    query GetComponentItem($projectId: String!, $componentId: String!) {
       item(projectId: $projectId, itemId: $componentId) {
           id name … on Component {
              tipVersion {
                 id
                 name
               }
          }
       }
    }
    
    Show More

    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
             }
          }
       }
    }
    
    Show More

    Change 5: Drawing no longer implements items

    Applicable Breaking Changes:

    • Drawing no longer implements items. Adjust all items queries to expect DrawingItem instead of Drawing.
    • DrawingItem and DrawingItemVersion types have been added.
    • DrawingFile and DrawingFileVersion types have been removed.

    Migration Steps:

    • To migrate, adjust all items queries to expect DrawingItem instead of Drawing.
    • You can go from a DrawingItem to a DrawingVersion by using the tipDrawing field.

    Before:

    query GetDrawingItem($projectId: String!, $drawingId: String!) {
     item(projectId: $projectId, itemId: $drawingId) {
       id
       name
       ... on Drawing {
          tipVersion {
          id
          name
          }
       }
     }
    }
    
    Show More

    After:

    query GetDrawing($drawingId: ID!) {
        drawing(drawingId: $drawingId) {
            id
            name
            tipVersion {
                id
                name
                componentVersion {
                    id
                    name
                }
                drawingItemVersion {
                    id
                    name
                }
            }
        }
    }
    
    Show More

    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
     }
    }
    
    Show More

    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
                }
            }
        }
    }
    
    Show More

    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 to folderId.

    Migration Steps:

    • To migrate, rename itemId to folderId.

    Before:

    query GetItems($projectId: String!, $folderId: String!) {
       items(projectId: $projectId, itemId: $folderId) {
          results {
                id
                name
          }
       }
    }
    
    Show More

    After:

    query GetFolderItemsByFolder($projectId: ID!, $folderId: ID!, $filter: ItemFilterInput) {
        itemsByFolder(projectId: $projectId, folderId: $folderId, filter: $filter) {
            results {
                __typename
                id
                name
            }
        }
    }
    
    Show More

    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 with hubId.

    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
                }
              }
            }
          }
    
    Show More

    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
    
          }
    
       }
    
    }
    
    Show More

    After:

    query GetFolderItemsByProject($projectId: ID!, $filter: ItemFilterInput) {
      itemsByProject(projectId: $projectId, filter: $filter) {
          results {
              __typename
              id
              name
          }
       }
    }
    
    Show More

    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
         }
       }
    }
    
    Show More

    After:

    query GetComponentVersion($componentVersionId: ID!) {
        componentVersion(componentVersionId: $componentVersionId) {
            id
            name
            partNumber
            partDescription
            designItemVersion {
                id
                name
                extensionType
            }
            thumbnail {
                status
                signedUrl
            }
            component {
                id
                name
            }
        }
     }
    
    Show More