Skip to content

Autodesk-Forge/forge-api-java-client

Repository files navigation

Forge Java SDK

Forge API: oAuth2 Data-Management OSS Model-Derivative Build Status

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

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

thumbnail

Support

[email protected]

About

Forge Java SDK: Provides Java SDK to help you easily integrate Forge REST APIs into the application

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages