Autodesk-Forge / forge-model.coordination.api-postman.collection

DEPRECATED

This repository has been deprecated and migrated to https://github.com/autodesk-platform-services/aps-model.coordination.api-postman.collection

Postman Collection for Model Coordination API

Description

This repository provides a postman collection that follows tutorials and API references for Model Coordination API on Forge developer portal. This API works with BIM360 and Autodesk Construction Cloud (ACC).

The API supports 3 legged token only.

Update: The Index v1 API of Model Coordination API is now deprecated. To get index of the models of Model Coordination, use Model Properties API. The collection in this repository provides some demo endpoints. To learn more details of Model Properties API, check the other Postman collection.

What's Postman?

Postman is a popular tool that provides an easy-to-use interface to send HTTP requests. Postman is able to parse the responses that Forge sends you and save response parameter values to variables. These parameters can then be reused in subsequent requests through these variables. The Postman collections in this repository use this ability to provide pre-populated HTTP requests to help you follow the tutorial workflow with minimal effort. You can also modify the requests and experiment without having to write a single line of code.

• You can learn how to install and use Postman from here.

• You can download the Postman installer from here.

Setup

1. Forge Account: Learn how to create a Forge Account, activate the subscription and create an app by this tutorial. Get Forge client id, client secret and callback url. Please register Forge app with the callback url as

   https://www.getpostman.com/oauth2/callback

2. BIM 360 (or ACC) Account and project: must be Account Admin to add the app integration. Learn about provisioning.

3. Upload some demo models to one file folder of in BIM360 or ACC. Some sample Revit models are available in the other repository.

4. Get BIM 360/ACC Docs project id (without b.) by other scripts of API, or copy from browser URL bar of Docs UI. And get the folder urn.

5. Clone this repository or download it. It's recommended to install GitHub Desktop. To clone it via command line, use the following (Terminal on MacOSX/Linux, Git Shell on Windows):

   git clone https://github.com/autodesk-forge/forge-model.coordination.api-postman.collection

6. Import the collection and environment files to Postman

7. In environment, input client id, client secret, mc container id (project id without b.) and folder urn

   

8. In the context menu of collection >> Edit, switch to the tab Authorization. Click Get New Access Token, input the variables as below:

   • Grant Type Authorization Codecom/

   • Callback URL https://www.getpostman.oauth2/callback

   • Auth URL https://developer.api.autodesk.com/authentication/v1/authorize

   • Access Token URL https://developer.api.autodesk.com/authentication/v1/gettoken

   • Client ID {{client_id}}

   • Client Secret {{client_secret}}

   • Scope data:readx

   • Client Authentication Send Client credentials body

   

9. Click Get New Access Token, it will direct to login Autodesk account, after it succeeds, the token will be generated. Click Use Token.

Model Properties API requires to work with 3-legged token. This collection takes Inheriting auth to apply 3-legged token to every endpoint in the collection automatically, which means it does not need to input the token in the header explicitly.

API Test

1. Assume the steps of Setup have been performed and the access token is ready.

2. When the coordinating space (with models) is ready. Play the tutorials or API references. Try to change some parameters or body for more scenarios to test.

   

Tutorials

1. Model Sets and Versions: this demos how to create a new model set (new model coordination space), coordinating an existing folder, how to get model sets and query model set versions. It also demo when you want to enable an deactivated modelset. When a new model set is created or is enabled, a job will start. Check its status by GET ModelSet Job Status. The pre-defined variables are: mc container id (project id without b.) and mc folder id (the folder urn of the model coordination space).

2. Model Set Version Clash: this demos how to get clash data of one clash test.The pre-defined variables are: mc container id (project id without b.) and modelSetId (one model set id from any previous scripts).

3. Model Index Properties - by Model Properties API: this demos how to get document properties(indexing) by Model Properties API with one query condition (views count >0). The pre-defined variables are: first model version urn and second model version urn. Check the other Postman collection for more guide about Model Properties API.

4. (Additional) If you know account name and project name only, you want to perform the some pre-steps: create new folder, upload two demo models, you can run the scripts: Optional Prerequisites Steps>>Prepare Folders and Models. Firstly input the account name and project name. Run the scripts one by one, including uploading the demo models to the new folder. The predefined variables will be as below:

   

API References

This section follows the same as API document.

1. Model Set: the endpoints to create model set, get model set, create clash issue, enable/disable model set etc.

   To test the endpoint of creating clash issue, it requires issue type id, issue root cause id, one user id. Please perform the steps by Optional Prerequisites Steps>>Get Definitions Data of Issue. Note: The endpoints to get issue type and root cause of Issue API of BIM360 and ACC are seperate .

2. Model Set: Versions: the endpoints to create or get model set version

3. Model Set: Views : the endpoints to get model set views, the documents with the views etc.

4. Clash Test: endpoints to get clash test and clash result.

5. Clash Test: Clash Groups Shared, Clash Test: Assigned Clash Groups, Clash Test: Closed Clash Groups: endpoints related with clash groups

6. Model Index Properties: endpoints to get indexing properties by Model Properties API

Further Materials

• Model Coordination API Reference
• Model Coordination API Tutorials
• Model Properties API Reference
• Querying Model Properties

Blogs:

• Forge Blog
• Field of View, a BIM focused blog

License

This sample is licensed under the terms of the MIT License. Please see the LICENSE file for full details.

Written by

Xiaodong Liang @coldwood, Developer Advacate and Support team