BIM 360 Issues Version 2 API Released

We are pleased to inform you about the general availability of BIM 360 Issues version 2 (v2) API.

The v2 API simplifies the format of response body (eliminating JSON:API format). It also provides additional features, such as local attachments. The basic functionality of BIM 360 Issues v2 API remains the same. Code changes are required, but should be straightforward. Below is the overview of differences between v1 and v2:

• The base url is changed from /v1/…/quality_issues to /v2/…/issues, e.g.,
  from 

https://developer.api.autodesk.com/issues/v1/containers/:container_id/quality-issues

         to

 https://developer.api.autodesk.com/issues/v2/containers/:containerId/issues 

• GET root-causes is replaced with GET issues-root-cause-categories. Fetching root cause category is added in v2
• The format of response has flat format in v2 as a result of moving away from JSON:API, making it easier to parse the response.
• No change with two endpoints: GET custom-attribute-definitions and GET custom-attribute-mappings. Those endpoints have been already from v2 and has /v2/ in the endpoints.

There are a few enhancements as well:

• Support for local attachment upload. A local attachment is stored in a hidden folder in BIM360 Docs. To complete the local attachment upload workflow, POST /attachments/:attachmentId is added.
• attachmentType of attachment adds “photo” type to indicates image (e.g., png, jpg.).

You may see better performance due to the internal implementation enhancement. Migration should be straightforward. Here are a couple of points to note on the scope in this release:

• Get/create pushpin issue is supported in a similar manner as v1 API. However, the data structure is changed; push-pin data is now under linkedDocuments instead of pushpin_attributes. Please refer to the updated tutorials “get pushpin issue” and  “create pushpin issue” for more detail.  
• Uploading local attachment will require to upload a file through S3 signed url. This is the standard way of using Data Management API. This tutorial describes the steps in detail.
• filter[qualityUrns] is used to filter issues associated with specific checklists. However, the response field for the checklists are called links in v2, not quality_urns (v1).

Documentation

• Field Guide
• Migration Guide: outlines and details of comparison of version 1 and version 2
• Step-by-Step Tutorials
  • Retrieve Container ID of Issue (no change)
  • Retrieve Issues Data
  • Create Issues Data
  • Attach BIM 360 Document Management Files to Issues
  • Retrieve Issue Custom Attributes Mapped to an Issue Type
  • Render Document-related (Pushpin) Issues and RFIs in Your App
  • Create Document-related (Pushpin) Issues and RFIs in Your App
  • Upload Local Attachment
• API References

GitHub

• Postman Collection 

Please be aware that the BIM 360 Issues v2 API is NOT COMPATIBLE with ACC projects. You will need to use the ACC version of Issues API for ACC projects. The format of requests and response data structure in the BIM 360 Issues v2 API follows the same standard that we use in Autodesk Construction Cloud (ACC) Issues API. You may find migrating to v2 as a step toward supporting ACC version.

Moving forward, for new development, please use the v2 API. If you already have an app using BIM 360 Issues v1 API, you will need to migrate to the v2 API. Please take a look at the new set of the v2 API at earliest to make sure you have everything you need to migrate to v2 API. If you have any questions or encounter issues, please contact us ASAP through our APS support channel.

2/9/2023 Update: BIM 360 Issues (v1) API is scheduled to retire on July 5, 2023. Please refer to this blog post.