Forge Java SDK

Forge API:

Overview

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

Requirements

• Java version 7 and above.
• A registered app on the Forge Developer portal.
• Apache Maven.

Install the Library

To install the API client library to your local Maven repository, simply execute:

mvn install

Maven users

Add the following dependency to your pom.xml:

<dependency>
   	<groupId>com.autodesk</groupId>
   	<artifactId>forge-java-sdk</artifactId>
   	<version>1.0.2</version>
</dependency>

Gradle users

Add this dependency to your project's build file:

repositories {
    mavenLocal()
}
dependencies {
    compile "com.autodesk:com-autodesk-client:1.0.2"
}

Tutorial

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

Learn Forge

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. This tutorial uses both 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:

String CLIENT_ID = "" , CLIENT_SECRET = "";
List<String> scopes = new ArrayList<String>();
scopes.add("data:read");
scopes.add("data:write");

// Initialize the 2-legged OAuth 2.0 client, and optionally set specific scopes.
// If you omit scopes, the generated token will have all scope permissions.
// Set autoRefresh to `true` to automatically refresh the access token when it expires.
OAuth2TwoLegged oauth2TwoLegged = new OAuth2TwoLegged(CLIENT_ID, CLIENT_SECRET, scopes, true);
Credentials twoLeggedCredentials = oauth2TwoLegged.authenticate();

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. Run this code to create a consent page URL:

String CLIENT_ID = "" , CLIENT_SECRET = "", REDIRECT_URL = "";
// Generate a url that asks permissions for specific scopes.
List<String> scopes = new ArrayList<String>();
scopes.add("data:read");
scopes.add("data:write");

// Initialize the 3-legged OAuth 2.0 client, and optionally set specific scopes.
// If you omit scopes, the generated token will have all scope permissions.
// Set autoRefresh to `true` to automatically refresh the access token when it expires.
// Note that the REDIRECT_URL must match the callback URL you provided when you created the app.
OAuth2ThreeLegged oauth2ThreeLegged = new OAuth2ThreeLegged(CLIENT_ID, CLIENT_SECRET, REDIRECT_URL, scopes, true);

// Generate a URL page that asks for permissions for the specified scopes.
String oauthUrl = oauth2ThreeLegged.getAuthenticationUrl();

//Redirect the user to authUrl (the user consent page).

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:

// The `threeLeggedCredentials` object contains an `access_token` and an optional `refresh_token` that you can use to call the endpoints.
ThreeLeggedCredentials threeLeggedCredentials = oauth2ThreeLegged.getAccessToken(authorizationCode);

Note that access tokens expire after a short period of time. The expiresAt field in the threeLeggedCredentials object gives the validity of an access token in seconds. To refresh your access token, call the oauth2ThreeLegged.refreshAccessToken(threeLeggedCredentials.getRefreshToken()); method.

Example API Calls

Use the threeLeggedCredentials object to call the Forge APIs.

import com.autodesk.client.ApiException;
import com.autodesk.client.ApiResponse;
import com.autodesk.client.api.BucketsApi;
import com.autodesk.client.api.HubsApi;
import com.autodesk.client.auth.*;
import com.autodesk.client.model.*;
import java.util.ArrayList;
import java.util.List;

public class ForgeApiExample {

    public static void main(String[] args) {

        try {
            List<String> scopes = new ArrayList<String>();
            scopes.add("data:read");
            scopes.add("data:write");
            scopes.add("bucket:create");
            scopes.add("bucket:read");

            // Initialize the oauth2TwoLegged object using the client key and client secret you received when creating the app on the Forge Developer portal:
            OAuth2TwoLegged oauth2TwoLegged = new OAuth2TwoLegged("<CLIENT_ID>", "<CLIENT_SECRET>", scopes, true);
            Credentials twoLeggedCredentials = oauth2TwoLegged.authenticate();

            // Initialize the relevant clients; in this example, the Hubs and Buckets clients (part of the Data Management API).
            BucketsApi bucketsApi = new BucketsApi();
            HubsApi hubsApi = new HubsApi();

            // Create a new bucket
            // Use the oauth2TwoLegged and twoLeggedCredentials objects that you retrieved previously.
            PostBucketsPayload payload = new PostBucketsPayload();
            payload.setBucketKey("test_bucket_key");
            payload.setPolicyKey(PostBucketsPayload.PolicyKeyEnum.PERSISTENT);
            ApiResponse<Bucket> createBucketResponse = bucketsApi.createBucket(payload, "", oauth2TwoLegged, twoLeggedCredentials);
            System.out.println(createBucketResponse.getData().getBucketKey());

            // Get the buckets owned by an application.
            // Use the oauth2TwoLegged and twoLeggedCredentials objects that you retrieved previously.
            ApiResponse<Buckets> getBucketsResponse = bucketsApi.getBuckets(null, null, null, oauth2TwoLegged, twoLeggedCredentials);
            for(BucketsItems bucket: getBucketsResponse.getData().getItems()) {
                System.out.println(bucket.getBucketKey());
            }

            // Get the hubs that are accessible for a member.
            // Use the oauth2ThreeLegged and threeLeggedCredentials objects that you retrieved previously.
            ApiResponse<Hubs> getHubsResponse = hubsApi.getHubs(null, null, oauth2ThreeLegged, threeLeggedCredentials);
            for(Hub hub: getHubsResponse.getData().getData()) {
                System.out.println(hub.getId());
            }

        } catch (Exception e) {
            System.err.println("Exception when calling Forge APIs");
            e.printStackTrace();
        }
    }
}

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
ActivitiesApi	createActivity	POST /autocad.io/us-east/v2/Activities	Creates a new Activity.
ActivitiesApi	deleteActivity	DELETE /autocad.io/us-east/v2/Activities('{id}')	Removes a specific Activity.
ActivitiesApi	deleteActivityHistory	POST /autocad.io/us-east/v2/Activities('{id}')/Operations.DeleteHistory	Removes the version history of the specified Activity.
ActivitiesApi	getActivity	GET /autocad.io/us-east/v2/Activities('{id}')	Returns the details of a specific Activity.
ActivitiesApi	getActivityVersions	GET /autocad.io/us-east/v2/Activities('{id}')/Operations.GetVersions	Returns all old versions of a specified Activity.
ActivitiesApi	getAllActivities	GET /autocad.io/us-east/v2/Activities	Returns the details of all Activities.
ActivitiesApi	patchActivity	PATCH /autocad.io/us-east/v2/Activities('{id}')	Updates an Activity by specifying only the changed attributes.
ActivitiesApi	setActivityVersion	POST /autocad.io/us-east/v2/Activities('{id}')/Operations.SetVersion	Sets the Activity to the specified version.
ActivitiesApi	updateActivity	PUT /autocad.io/us-east/v2/Activities('{id}')	Updates an Activity by redefining the entire Activity object.
AppPackagesApi	createAppPackage	POST /autocad.io/us-east/v2/AppPackages	Creates an AppPackage module.
AppPackagesApi	deleteAppPackage	DELETE /autocad.io/us-east/v2/AppPackages('{id}')	Removes a specific AppPackage.
AppPackagesApi	deleteAppPackageHistory	POST /autocad.io/us-east/v2/AppPackages('{id}')/Operations.DeleteHistory	Removes the version history of the specified AppPackage.
AppPackagesApi	getAllAppPackages	GET /autocad.io/us-east/v2/AppPackages	Returns the details of all AppPackages.
AppPackagesApi	getAppPackage	GET /autocad.io/us-east/v2/AppPackages('{id}')	Returns the details of a specific AppPackage.
AppPackagesApi	getAppPackageVersions	GET /autocad.io/us-east/v2/AppPackages('{id}')/Operations.GetVersions	Returns all old versions of a specified AppPackage.
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.
AppPackagesApi	getUploadUrlWithRequireContentType	GET /autocad.io/us-east/v2/AppPackage/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.
AppPackagesApi	patchAppPackage	PATCH /autocad.io/us-east/v2/AppPackages('{id}')	Updates an AppPackage by specifying only the changed attributes.
AppPackagesApi	setAppPackageVersion	POST /autocad.io/us-east/v2/AppPackages('{id}')/Operations.SetVersion	Sets the AppPackage to the specified version.
AppPackagesApi	updateAppPackage	PUT /autocad.io/us-east/v2/AppPackages('{id}')	Updates an AppPackage by redefining the entire Activity object.
BucketsApi	createBucket	POST /oss/v2/buckets
BucketsApi	deleteBucket	DELETE /oss/v2/buckets/{bucketKey}
BucketsApi	getBucketDetails	GET /oss/v2/buckets/{bucketKey}/details
BucketsApi	getBuckets	GET /oss/v2/buckets
DerivativesApi	deleteManifest	DELETE /modelderivative/v2/designdata/{urn}/manifest
DerivativesApi	getDerivativeManifest	GET /modelderivative/v2/designdata/{urn}/manifest/{derivativeUrn}
DerivativesApi	getFormats	GET /modelderivative/v2/designdata/formats
DerivativesApi	getManifest	GET /modelderivative/v2/designdata/{urn}/manifest
DerivativesApi	getMetadata	GET /modelderivative/v2/designdata/{urn}/metadata
DerivativesApi	getModelviewMetadata	GET /modelderivative/v2/designdata/{urn}/metadata/{guid}
DerivativesApi	getModelviewProperties	GET /modelderivative/v2/designdata/{urn}/metadata/{guid}/properties
DerivativesApi	getThumbnail	GET /modelderivative/v2/designdata/{urn}/thumbnail
DerivativesApi	translate	POST /modelderivative/v2/designdata/job
EnginesApi	getAllEngines	GET /autocad.io/us-east/v2/Engines	Returns the details of all available AutoCAD core engines.
EnginesApi	getEngine	GET /autocad.io/us-east/v2/Engines('{id}')	Returns the details of a specific AutoCAD core engine.
FoldersApi	getFolder	GET /data/v1/projects/{project_id}/folders/{folder_id}
FoldersApi	getFolderContents	GET /data/v1/projects/{project_id}/folders/{folder_id}/contents
FoldersApi	getFolderParent	GET /data/v1/projects/{project_id}/folders/{folder_id}/parent
FoldersApi	getFolderRefs	GET /data/v1/projects/{project_id}/folders/{folder_id}/refs
FoldersApi	getFolderRelationshipsRefs	GET /data/v1/projects/{project_id}/folders/{folder_id}/relationships/refs
FoldersApi	postFolderRelationshipsRef	POST /data/v1/projects/{project_id}/folders/{folder_id}/relationships/refs
HubsApi	getHub	GET /project/v1/hubs/{hub_id}
HubsApi	getHubs	GET /project/v1/hubs
ItemsApi	getItem	GET /data/v1/projects/{project_id}/items/{item_id}
ItemsApi	getItemParentFolder	GET /data/v1/projects/{project_id}/items/{item_id}/parent
ItemsApi	getItemRefs	GET /data/v1/projects/{project_id}/items/{item_id}/refs
ItemsApi	getItemRelationshipsRefs	GET /data/v1/projects/{project_id}/items/{item_id}/relationships/refs
ItemsApi	getItemTip	GET /data/v1/projects/{project_id}/items/{item_id}/tip
ItemsApi	getItemVersions	GET /data/v1/projects/{project_id}/items/{item_id}/versions
ItemsApi	postItemRelationshipsRef	POST /data/v1/projects/{project_id}/items/{item_id}/relationships/refs
ItemsApi	postItem	POST /data/v1/projects/{project_id}/items
ObjectsApi	copyTo	PUT /oss/v2/buckets/{bucketKey}/objects/{objectName}/copyTo/{newObjName}
ObjectsApi	createSignedResource	POST /oss/v2/buckets/{bucketKey}/objects/{objectName}/signed
ObjectsApi	deleteObject	DELETE /oss/v2/buckets/{bucketKey}/objects/{objectName}
ObjectsApi	deleteSignedResource	DELETE /oss/v2/signedresources/{id}
ObjectsApi	getObject	GET /oss/v2/buckets/{bucketKey}/objects/{objectName}
ObjectsApi	getObjectDetails	GET /oss/v2/buckets/{bucketKey}/objects/{objectName}/details
ObjectsApi	getObjects	GET /oss/v2/buckets/{bucketKey}/objects
ObjectsApi	getStatusBySessionId	GET /oss/v2/buckets/{bucketKey}/objects/{objectName}/status/{sessionId}
ObjectsApi	getSignedResource	GET /oss/v2/signedresources/{id}
ObjectsApi	uploadChunk	PUT /oss/v2/buckets/{bucketKey}/objects/{objectName}/resumable
ObjectsApi	uploadObject	PUT /oss/v2/buckets/{bucketKey}/objects/{objectName}
ObjectsApi	uploadSignedResource	PUT /oss/v2/signedresources/{id}
ObjectsApi	uploadSignedResourcesChunk	PUT /oss/v2/signedresources/{id}/resumable
ProjectsApi	getProject	GET /project/v1/hubs/{hub_id}/projects/{project_id}
ProjectsApi	getProjectHub	GET /project/v1/hubs/{hub_id}/projects/{project_id}/hub
ProjectsApi	postStorage	POST /data/v1/projects/{project_id}/storage
ProjectsApi	postVersion	POST /data/v1/projects/{project_id}/versions
ProjectsApi	getHubProjects	GET /project/v1/hubs/{hub_id}/projects
VersionsApi	getVersion	GET /data/v1/projects/{project_id}/versions/{version_id}
VersionsApi	getVersionItem	GET /data/v1/projects/{project_id}/versions/{version_id}/item
VersionsApi	getVersionRefs	GET /data/v1/projects/{project_id}/versions/{version_id}/refs
VersionsApi	getVersionRelationshipsRefs	GET /data/v1/projects/{project_id}/versions/{version_id}/relationships/refs
VersionsApi	postVersionRelationshipsRef	POST /data/v1/projects/{project_id}/versions/{version_id}/relationships/refs
WorkItemsApi	createWorkItem	POST /autocad.io/us-east/v2/WorkItems	Creates a new WorkItem.
WorkItemsApi	deleteWorkItem	DELETE /autocad.io/us-east/v2/WorkItems('{id}')	Removes a specific WorkItem.
WorkItemsApi	getAllWorkItems	GET /autocad.io/us-east/v2/WorkItems	Returns the details of all WorkItems.
WorkItemsApi	getWorkItem	GET /autocad.io/us-east/v2/WorkItems('{id}')	Returns the details of a specific WorkItem.

Thumbnail

Support

[email protected]