Autodesk Forge APIs: Migrating from v1 to v2

September 8, 2016

By @ShiyaLuo

Forge DevCon announced a new version of APIs to upload, translate and view your CAD files. Many of our early adopters have started with developing with View and Data API, which is actually a set of RESTful APIs along with a JavaScript viewer. This post will focus on how to migrate from v1 to v2. It’s not going to talk about the new features of v2 that v1 did not implement, just a guide to change your code from v1 so it will run with v2 API when v1 is eventually deprecated.

In v2, the View and Data API have separated into three parts:

  1. Data Management API
  2. Model Derivative API
  3. Viewer

Scoped Tokens

First and foremost, the biggest change that is going to affect the most number of developers is scoped tokens. After the Forge DevCon, every new app created will required a scoped token. A scoped token is retrieved when you include a scope value in the body of a x-www-form-urlencoded string.

v1

In v1, a token is requested like this:

POST /authentication/v1/authenticate HTTP/1.1
Host: developer.api.autodesk.com
Content-Type: application/x-www-form-urlencoded

client_id=YOUR-ID&client_secret=YOUR-SECRET&grant_type=client_credentials

v2

In v2, add the scope of the token you’d like to retrieve. There’s a detailed post about scopes. The best practice is to only include the scopes you need, especially not to use a data:write or bucket:write scoped token in the client-side viewer.

POST /authentication/v1/authenticate HTTP/1.1
Host: developer.api.autodesk.com
Content-Type: application/x-www-form-urlencoded

client_id=YOUR-ID&client_secret=YOUR-SECRET&grant_type=client_credentials&scope=data%3Aread+data%3Acreate+data%3Awrite+bucket%3Aread+bucket%3Acreate

Object Storage Service (OSS)

OSS in the View and Data API is now under the Data Management API.

Migrating from v1 to v2 for APIs from OSS is fairly straight forward. The paths did not change except for version numbers. For example, create a bucket used to have a path of /oss/v1/buckets, it just changed to /oss/v2/buckets.

Scopes required in OSS is usually bucket:create or bucket:read.

Reference Service

Reference service is not an API you call anymore with v2. You no longer have to upload individual files, set references and translate the master file. With v2, just upload the files as a zip file, and declare the root file name in the body. A more detailed explanation is posted on the developer portal.

Viewing Service

Viewing service is now under model derivative API. The paths have changed from /viewingservice/ to /modelderivative/.

To migrate from v1 to v2, change the path to the following APIs:

  1. Supported formats
  • v1: GET /viewingservice/v1/supported
  • v2: GET /modelderivative/v2/designdata/formats
  1. Register for translation (Post a job)

    The register for translation API change since we can now translate one file formats into multiple different outputs, as opposed to let viewer 3D consume it.

  • v1: POST /viewingservice/v1/register

    request body:

    {
      "urn": "{{base64Urn}}"
    }
    
  • v2: POST /modelderivative/v2/designdata/job

    request body:

    {
      "input": {
          "urn": "{{base64Urn}}"
      },
      "output": {
          "destination": {
              "region": "us"
          },
          "formats": [
          {
              "type": "svf",
              "views":["2d", "3d"]
          }]
      }
    }
    

Happy coding!

Posts by author

Shiya's Profile Pic

Shiya is a Developer Evangelist at Autodesk. She creates content around Autodesk's Web Service APIs and the WebGL Viewer.