Forge Node.js SDK

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.

Overview

This Node.js SDK enables you to easily integrate the Forge REST APIs into your application, including OAuth, Data Management, Model Derivative,

Requirements

• 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.

Installation

    npm install forge-apis --save

Tutorial

Follow this tutorial to see a step-by-step authentication guide, and examples of how to use the Forge APIs.

Create an App

Create an app on the Forge Developer portal. Note the client ID and client secret.

Authentication

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.

2-Legged Token

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.

var ForgeSDK = require('forge-apis');
var APS_CLIENT_ID = '<your-client-id>' , APS_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 refresh
var autoRefresh = true; // or false

var oAuth2TwoLegged = new ForgeSDK.AuthClientTwoLegged(APS_CLIENT_ID, APS_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);
});

3-Legged Token

Generate an Authentication URL

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.

var ForgeSDK = require('forge-apis');
var APS_CLIENT_ID = '<your-client-id>', APS_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 refresh
var autoRefresh = true;
var oAuth2ThreeLegged = new ForgeSDK.AuthClientThreeLegged(APS_CLIENT_ID, APS_CLIENT_SECRET, REDIRECT_URL, [
    'data:read',
    'data:write'
], autoRefresh);

// Generate a URL page that asks for permissions for the specified scopes.
oAuth2ThreeLegged.generateAuthUrl();

Retrieve an Authorization Code

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}

Retrieve an Access Token

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.

Example API Calls

Use the oauth2client (2-legged or 3-legged) object and the credentials object to call the Forge APIs.

// Import the library.
var ForgeSDK = require('forge-apis');

// Initialize the relevant clients; in this example, the Hubs and Buckets clients (part of the Data Management API).
var HubsApi = new ForgeSDK.HubsApi(); //Hubs Client
var BucketsApi = new ForgeSDK.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 work
BucketsApi.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 step
HubsApi.getHubs({}, oAuth2ThreeLegged, credentials).then(function(hubs) {
    console.log(hubs);
}, function(err){
     console.error(err);
});

API Documentation

You can get the full documentation for the API on the Developer Portal

Documentation for API Endpoints

All URIs are relative to https://developer.api.autodesk.com/ (for example createBucket URI is 'https://developer.api.autodesk.com/oss/v2/buckets')

DerivativesApi regions

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:

var DerivativesApi = new ForgeSDK.DerivativesApi(); // defaults to US
var DerivativesApi = new ForgeSDK.DerivativesApi(undefined, 'EMEA'); // Use EMEA endpoint
var DerivativesApi = new ForgeSDK.DerivativesApi(undefined, 'EU'); // Use EMEA endpoint
var DerivativesApi = new ForgeSDK.DerivativesApi(undefined, 'US'); // Use US endpoint

Classes

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	getFormats	GET /modelderivative/v2/designdata/formats
ForgeSdk.DerivativesApi	translate	POST /modelderivative/v2/designdata/job
ForgeSdk.DerivativesApi	setReferences	POST /modelderivative/v2/designdata/{urn}/references
ForgeSdk.DerivativesApi	getThumbnail	GET /modelderivative/v2/designdata/{urn}/thumbnail
ForgeSdk.DerivativesApi	getManifest	GET /modelderivative/v2/designdata/{urn}/manifest
ForgeSdk.DerivativesApi	deleteManifest	DELETE /modelderivative/v2/designdata/{urn}/manifest
ForgeSdk.DerivativesApi	getDerivativeManifest	GET /modelderivative/v2/designdata/{urn}/manifest/{derivativeUrn}
ForgeSdk.DerivativesApi	getDerivativeManifestInfo	HEAD /modelderivative/v2/designdata/{urn}/manifest/{derivativeUrn}
ForgeSdk.DerivativesApi	getDerivativeDownloadUrl	GET /modelderivative/v2/designdata/{urn}/manifest/{derivativeUrn}/signedcookies
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.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

Thumbnail

Support

forge.help@autodesk.com