Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

forge-apis

0.4.4 • Public • Published

Forge Node.js SDK Build Status

Forge API: oAuth2 Data-Management OSS Model-Derivative

Overview

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

Requirements

  • Node.js version 4 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 CLIENT_ID = '<your-client-id>' , 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(CLIENT_ID, 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 CLIENT_ID = '<your-client-id>', 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(CLIENT_ID, 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')

Class Method HTTP request Description
ForgeSdk.ActivitiesApi createActivity POST /autocad.io/us-east/v2/Activities Creates a new Activity.
ForgeSdk.ActivitiesApi deleteActivity DELETE /autocad.io/us-east/v2/Activities(%27{id}%27) Removes a specific Activity.
ForgeSdk.ActivitiesApi deleteActivityHistory POST /autocad.io/us-east/v2/Activities(%27{id}%27)/Operations.DeleteHistory Removes the version history of the specified Activity.
ForgeSdk.ActivitiesApi getActivity GET /autocad.io/us-east/v2/Activities(%27{id}%27) Returns the details of a specific Activity.
ForgeSdk.ActivitiesApi getActivityVersions GET /autocad.io/us-east/v2/Activities(%27{id}%27)/Operations.GetVersions Returns all old versions of a specified Activity.
ForgeSdk.ActivitiesApi getAllActivities GET /autocad.io/us-east/v2/Activities Returns the details of all Activities.
ForgeSdk.ActivitiesApi patchActivity PATCH /autocad.io/us-east/v2/Activities(%27{id}%27) Updates an Activity by specifying only the changed attributes.
ForgeSdk.ActivitiesApi setActivityVersion POST /autocad.io/us-east/v2/Activities(%27{id}%27)/Operations.SetVersion Sets the Activity to the specified version.
ForgeSdk.AppPackagesApi createAppPackage POST /autocad.io/us-east/v2/AppPackages Creates an AppPackage module.
ForgeSdk.AppPackagesApi deleteAppPackage DELETE /autocad.io/us-east/v2/AppPackages(%27{id}%27) Removes a specific AppPackage.
ForgeSdk.AppPackagesApi deleteAppPackageHistory POST /autocad.io/us-east/v2/AppPackages(%27{id}%27)/Operations.DeleteHistory Removes the version history of the specified AppPackage.
ForgeSdk.AppPackagesApi getAllAppPackages GET /autocad.io/us-east/v2/AppPackages Returns the details of all AppPackages.
ForgeSdk.AppPackagesApi getAppPackage GET /autocad.io/us-east/v2/AppPackages(%27{id}%27) Returns the details of a specific AppPackage.
ForgeSdk.AppPackagesApi getAppPackageVersions GET /autocad.io/us-east/v2/AppPackages(%27{id}%27)/Operations.GetVersions Returns all old versions of a specified AppPackage.
ForgeSdk.AppPackagesApi getUploadUrl GET /autocad.io/us-east/v2/AppPackages/Operations.GetUploadUrl Requests a pre-signed URL for uploading a zip file that contains the binaries for this AppPackage.
ForgeSdk.AppPackagesApi getUploadUrlWithRequireContentType GET /autocad.io/us-east/v2/AppPackages/Operations.GetUploadUrl(RequireContentType={require}) Requests a pre-signed URL for uploading a zip file that contains the binaries for this AppPackage. Unlike the GetUploadUrl method that takes no parameters, this method allows the client to request that the pre-signed URL to be issued so that the subsequent HTTP PUT operation will require Content-Type=binary/octet-stream.
ForgeSdk.AppPackagesApi patchAppPackage PATCH /autocad.io/us-east/v2/AppPackages(%27{id}%27) Updates an AppPackage by specifying only the changed attributes.
ForgeSdk.AppPackagesApi setAppPackageVersion POST /autocad.io/us-east/v2/AppPackages(%27{id}%27)/Operations.SetVersion Sets the AppPackage to the specified version.
ForgeSdk.AppPackagesApi updateAppPackage PUT /autocad.io/us-east/v2/AppPackages(%27{id}%27) Updates an AppPackage by redefining the entire Activity object.
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.EnginesApi getAllEngines GET /autocad.io/us-east/v2/Engines Returns the details of all available AutoCAD core engines.
ForgeSdk.EnginesApi getEngine GET /autocad.io/us-east/v2/Engines(%27{id}%27) Returns the details of a specific AutoCAD core engine.
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
ForgeSdk.WorkItemsApi createWorkItem POST /autocad.io/us-east/v2/WorkItems Creates a new WorkItem.
ForgeSdk.WorkItemsApi deleteWorkItem DELETE /autocad.io/us-east/v2/WorkItems(%27{id}%27) Removes a specific WorkItem.
ForgeSdk.WorkItemsApi getAllWorkItems GET /autocad.io/us-east/v2/WorkItems Returns the details of all WorkItems.
ForgeSdk.WorkItemsApi getWorkItem GET /autocad.io/us-east/v2/WorkItems(%27{id}%27) Returns the details of a specific WorkItem.

Thumbnail

thumbnail

Support

forge.help@autodesk.com

install

npm i forge-apis

Downloadsweekly downloads

756

version

0.4.4

license

Apache-2.0

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
  • avatar
Report a vulnerability