Forge API:
NOTE: The Design Automation v2 API is deprecated in this module. Instead move to the Design Automation v3 API using this NPM package
This Version includes Data Management filters and pagination, and the Data Management 'Commands' API.
This Node.js SDK enables you to easily integrate the Forge REST APIs into your application, including OAuth, Data Management, Model Derivative,
- Node.js version 10.12 and above.
- A registered app on the Forge Developer portal.
- A Node.js web server (such as Express) for 3-legged authentication.
npm install forge-apis --saveFollow this tutorial to see a step-by-step authentication guide, and examples of how to use the Forge APIs.
Create an app on the Forge Developer portal. Note the client ID and client secret.
This SDK comes with an OAuth 2.0 client that allows you to retrieve 2-legged and 3-legged tokens. It also enables you to refresh 3-legged tokens. The tutorial uses 2-legged and 3-legged tokens for calling different Data Management endpoints.
This type of token is given directly to the application.
To get a 2-legged token run the following code. Note that you need to replace your-client-id and your-client-secret with your app's client ID and client secret.
varForgeSDK=require('forge-apis');varFORGE_CLIENT_ID='<your-client-id>',FORGE_CLIENT_SECRET='<your-client-secret>';// Initialize the 2-legged OAuth2 client, set specific scopes and optionally set the `autoRefresh` parameter to true// if you want the token to auto refreshvarautoRefresh=true;// or falsevaroAuth2TwoLegged=newForgeSDK.AuthClientTwoLegged(FORGE_CLIENT_ID,FORGE_CLIENT_SECRET,['data:read','data:write'],autoRefresh);oAuth2TwoLegged.authenticate().then(function(credentials){// The `credentials` object contains an access_token that is being used to call the endpoints.// In addition, this object is applied globally on the oAuth2TwoLegged client that you should use when calling secure endpoints.},function(err){console.error(err);});To ask for permissions from a user to retrieve an access token, you redirect the user to a consent page.
Replace your-client-id, your-client-secret, and your-redirect-url with your app's client ID, client secret, and redirect URL, and run the code to create a consent page URL.
Note that the redirect URL must match the pattern of the callback URL field of the app’s registration in the My Apps section. The pattern may include wildcards after the hostname, allowing different redirect URL values to be specified in different parts of your app.
varForgeSDK=require('forge-apis');varFORGE_CLIENT_ID='<your-client-id>',FORGE_CLIENT_SECRET='<your-client-secret>',REDIRECT_URL='<your-redirect-url>';// Initialize the 3-legged OAuth2 client, set specific scopes and optionally set the `autoRefresh` parameter to true// if you want the token to auto refreshvarautoRefresh=true;varoAuth2ThreeLegged=newForgeSDK.AuthClientThreeLegged(FORGE_CLIENT_ID,FORGE_CLIENT_SECRET,REDIRECT_URL,['data:read','data:write'],autoRefresh);// Generate a URL page that asks for permissions for the specified scopes.oAuth2ThreeLegged.generateAuthUrl();Once a user receives permissions on the consent page, Forge will redirect the page to the redirect URL you provided when you created the app. An authorization code is returned in the query string.
GET /callback?code={authorizationCode}
Request an access token using the authorization code you received, as shown below:
oAuth2ThreeLegged.getToken(authorizationCode).then(function(credentials){// The `credentials` object contains an `access_token` and an optional `refresh_token` that you can use to call the endpoints.},function(err){console.error(err);});Note that access tokens expire after a short period of time. The expires_in field in the credentials object gives
the validity of an access token in seconds. To refresh your access token, call the oAuth2ThreeLegged.refreshToken(credentials); method.
Use the oauth2client (2-legged or 3-legged) object and the credentials object to call the Forge APIs.
// Import the library.varForgeSDK=require('forge-apis');// Initialize the relevant clients; in this example, the Hubs and Buckets clients (part of the Data Management API).varHubsApi=newForgeSDK.HubsApi();//Hubs ClientvarBucketsApi=newForgeSDK.BucketsApi();//Buckets Client// Get the buckets owned by an application.// Use the oAuth2TwoLegged client object and the credentials object that were// obtained from the previous step// notice that you need do add a bucket:read scope for the getBuckets to workBucketsApi.getBuckets({},oAuth2TwoLegged,credentials).then(function(buckets){console.log(buckets);},function(err){console.error(err);});// Get the hubs that are accessible for a member.// Use the oAuth2ThreeLegged client object and the credentials object that were// obtained from the previous stepHubsApi.getHubs({},oAuth2ThreeLegged,credentials).then(function(hubs){console.log(hubs);},function(err){console.error(err);});You can get the full documentation for the API on the Developer Portal
All URIs are relative to https://developer.api.autodesk.com/ (for example createBucket URI is 'https://developer.api.autodesk.com/oss/v2/buckets')
ForgeSDK.DerivativesApi(apiClient=null,region='US');// defaults to US// if null/undefined, apiClient defaults to the default ForgeSDK.ApiClient.instance| Region | Path |
|---|---|
| US | /modelderivative/v2/ |
| EMEA | /modelderivative/v2/regions/eu/ |
| EU | /modelderivative/v2/regions/eu/ |
ex:
varDerivativesApi=newForgeSDK.DerivativesApi();// defaults to USvarDerivativesApi=newForgeSDK.DerivativesApi(undefined,'EMEA');// Use EMEA endpointvarDerivativesApi=newForgeSDK.DerivativesApi(undefined,'EU');// Use EMEA endpointvarDerivativesApi=newForgeSDK.DerivativesApi(undefined,'US');// Use US endpoint| Class | Method | HTTP request | Description |
|---|---|---|---|
| ForgeSdk.BucketsApi | createBucket | POST /oss/v2/buckets | |
| ForgeSdk.BucketsApi | deleteBucket | DELETE /oss/v2/buckets/{bucketKey} | |
| ForgeSdk.BucketsApi | getBucketDetails | GET /oss/v2/buckets/{bucketKey}/details | |
| ForgeSdk.BucketsApi | getBuckets | GET /oss/v2/buckets | |
| ForgeSdk.DerivativesApi | deleteManifest | DELETE /modelderivative/v2/designdata/{urn}/manifest | |
| ForgeSdk.DerivativesApi | getDerivativeManifest | GET /modelderivative/v2/designdata/{urn}/manifest/{derivativeUrn} | |
| ForgeSdk.DerivativesApi | getFormats | GET /modelderivative/v2/designdata/formats | |
| ForgeSdk.DerivativesApi | getManifest | GET /modelderivative/v2/designdata/{urn}/manifest | |
| ForgeSdk.DerivativesApi | getMetadata | GET /modelderivative/v2/designdata/{urn}/metadata | |
| ForgeSdk.DerivativesApi | getModelviewMetadata | GET /modelderivative/v2/designdata/{urn}/metadata/{guid} | |
| ForgeSdk.DerivativesApi | getModelviewProperties | GET /modelderivative/v2/designdata/{urn}/metadata/{guid}/properties | |
| ForgeSdk.DerivativesApi | getThumbnail | GET /modelderivative/v2/designdata/{urn}/thumbnail | |
| ForgeSdk.DerivativesApi | translate | POST /modelderivative/v2/designdata/job | |
| ForgeSdk.FoldersApi | getFolder | GET /data/v1/projects/{project_id}/folders/{folder_id} | |
| ForgeSdk.FoldersApi | getFolderContents | GET /data/v1/projects/{project_id}/folders/{folder_id}/contents | |
| ForgeSdk.FoldersApi | getFolderParent | GET /data/v1/projects/{project_id}/folders/{folder_id}/parent | |
| ForgeSdk.FoldersApi | getFolderRefs | GET /data/v1/projects/{project_id}/folders/{folder_id}/refs | |
| ForgeSdk.FoldersApi | getFolderRelationshipsRefs | GET /data/v1/projects/{project_id}/folders/{folder_id}/relationships/refs | |
| ForgeSdk.FoldersApi | postFolder | POST /data/v1/projects/{project_id}/folders | |
| ForgeSdk.FoldersApi | postFolderRelationshipsRef | POST /data/v1/projects/{project_id}/folders/{folder_id}/relationships/refs | |
| ForgeSdk.HubsApi | getHub | GET /project/v1/hubs/{hub_id} | |
| ForgeSdk.HubsApi | getHubs | GET /project/v1/hubs | |
| ForgeSdk.ItemsApi | getItem | GET /data/v1/projects/{project_id}/items/{item_id} | |
| ForgeSdk.ItemsApi | getItemParentFolder | GET /data/v1/projects/{project_id}/items/{item_id}/parent | |
| ForgeSdk.ItemsApi | getItemRefs | GET /data/v1/projects/{project_id}/items/{item_id}/refs | |
| ForgeSdk.ItemsApi | getItemRelationshipsRefs | GET /data/v1/projects/{project_id}/items/{item_id}/relationships/refs | |
| ForgeSdk.ItemsApi | getItemTip | GET /data/v1/projects/{project_id}/items/{item_id}/tip | |
| ForgeSdk.ItemsApi | getItemVersions | GET /data/v1/projects/{project_id}/items/{item_id}/versions | |
| ForgeSdk.ItemsApi | postItem | POST /data/v1/projects/{project_id}/items | |
| ForgeSdk.ItemsApi | postItemRelationshipsRef | POST /data/v1/projects/{project_id}/items/{item_id}/relationships/refs | |
| ForgeSdk.ObjectsApi | copyTo | PUT /oss/v2/buckets/{bucketKey}/objects/{objectName}/copyto/{newObjName} | |
| ForgeSdk.ObjectsApi | createSignedResource | POST /oss/v2/buckets/{bucketKey}/objects/{objectName}/signed | |
| ForgeSdk.ObjectsApi | deleteObject | DELETE /oss/v2/buckets/{bucketKey}/objects/{objectName} | |
| ForgeSdk.ObjectsApi | deleteSignedResource | DELETE /oss/v2/signedresources/{id} | |
| ForgeSdk.ObjectsApi | getObject | GET /oss/v2/buckets/{bucketKey}/objects/{objectName} | |
| ForgeSdk.ObjectsApi | getObjectDetails | GET /oss/v2/buckets/{bucketKey}/objects/{objectName}/details | |
| ForgeSdk.ObjectsApi | getObjects | GET /oss/v2/buckets/{bucketKey}/objects | |
| ForgeSdk.ObjectsApi | getSignedResource | GET /oss/v2/signedresources/{id} | |
| ForgeSdk.ObjectsApi | getStatusBySessionId | GET /oss/v2/buckets/{bucketKey}/objects/{objectName}/status/{sessionId} | |
| ForgeSdk.ObjectsApi | uploadChunk | PUT /oss/v2/buckets/{bucketKey}/objects/{objectName}/resumable | |
| ForgeSdk.ObjectsApi | uploadObject | PUT /oss/v2/buckets/{bucketKey}/objects/{objectName} | |
| ForgeSdk.ObjectsApi | uploadSignedResource | PUT /oss/v2/signedresources/{id} | |
| ForgeSdk.ObjectsApi | uploadSignedResourcesChunk | PUT /oss/v2/signedresources/{id}/resumable | |
| ForgeSdk.ProjectsApi | getHubProjects | GET /project/v1/hubs/{hub_id}/projects | |
| ForgeSdk.ProjectsApi | getProject | GET /project/v1/hubs/{hub_id}/projects/{project_id} | |
| ForgeSdk.ProjectsApi | getProjectHub | GET /project/v1/hubs/{hub_id}/projects/{project_id}/hub | |
| ForgeSdk.ProjectsApi | getProjectTopFolders | GET /project/v1/hubs/{hub_id}/projects/{project_id}/topFolders | |
| ForgeSdk.ProjectsApi | postStorage | POST /data/v1/projects/{project_id}/storage | |
| ForgeSdk.UserProfileApi | getUserProfile | GET /userprofile/v1/users/@me | Returns the profile information of an authorizing end user. |
| ForgeSdk.VersionsApi | getVersion | GET /data/v1/projects/{project_id}/versions/{version_id} | |
| ForgeSdk.VersionsApi | getVersionItem | GET /data/v1/projects/{project_id}/versions/{version_id}/item | |
| ForgeSdk.VersionsApi | getVersionRefs | GET /data/v1/projects/{project_id}/versions/{version_id}/refs | |
| ForgeSdk.VersionsApi | getVersionRelationshipsRefs | GET /data/v1/projects/{project_id}/versions/{version_id}/relationships/refs | |
| ForgeSdk.VersionsApi | postVersion | POST /data/v1/projects/{project_id}/versions | |
| ForgeSdk.VersionsApi | postVersionRelationshipsRef | POST /data/v1/projects/{project_id}/versions/{version_id}/relationships/refs |
