Tutorial using cURL from 3 legged Authentication to BIM 360 Docs Upload

June 6, 2017

In this previous post, I showed you the entire workflow to Store a model in your own Team Service Hub. Today this tutorial will be very similar to that one, with the difference that you will have a chance to manage your data to BIM 360 Docs product. I will show you how to achieve the upload to BIM 360 Docs using 3 legged authentication and the Forge Data Management API. The steps we will take will be the following. If you want to see the Documentation tutorial, you can find it here.

The steps we will take will be the following. 

  1. Authorization Web Flow (This will return us the code we need to obtain our oauth token)
  2. Rest call to the Authentication API to obtain a 3 legged Token
  3. GET call to obtain detail of which Hubs do we have access in BIM 360 Docs (Registration of APP required for BIM 360 API access)
  4. GET call to find the project that has your resource
  5. GET call to find the folder where the upload will happen (Plans, Project File, Drawings).
    1. Extra step can include the access to a sub-folder.
  6. POST call to create a storage location in the previously defined folder
  7. PUT call to upload file to the storage location
  8. POST call to create the first version of the uploaded file.
  9. Check BIM 360 Docs to see your recently uploaded file.

Let's get started. I will be using the same structure for the cURL commands stated in the documentation, I will be providing links to the locations of every call I make. We will start with the authorization web flow in order to obtain our code. You can quickly pass in the following url to in your browser: Don't click on the floowing text since it is only for reference. More about this URL can be found here.

https://developer.api.autodesk.com/authentication/v1/authorize?response_type=code&client_id=YOURAPICLIENTID&redirect_uri=YOURURLCALLBACK&scope=THENEDDEDSCOPES 

I recommend using Chrome with Incognito mode in order to avoid any cached access data you may have done in the past. I created a simple HTML page with the Iframe tag mentioned in the documentation, so I have something to click and make my workflow simpler.

Here is the code for the quick and simple HTML Web Authorization Flow.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <!-- The above 3 meta tags *must* come first in the head; any other head content must come *after* these tags -->
    <meta name="description" content="">
    <meta name="author" content="">
    <link rel="icon" href="../../favicon.ico">

    <title>Forge Authorization Flow</title>

    <!-- Latest compiled and minified CSS -->
    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">

    <!-- Optional theme -->
    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap-theme.min.css" integrity="sha384-rHyoN1iRsVXV4nD0JutlnGaslCJuC7uwjduW9SVrLvRYooPp2bWYgmgJQIXwl/Sp" crossorigin="anonymous">

    <!-- Latest compiled and minified JavaScript -->
    <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous"></script>

  </head>

  <body>

    <div class="site-wrapper">

      <div class="site-wrapper-inner">

        <div class="cover-container">

          <div class="masthead clearfix">
            <div class="inner">
              <h3 class="masthead-brand">3 Legged Authorization WebFlow</h3>
            </div>
          </div>

          <div class="inner cover">
            <p class="lead">
              <a href="https://developer.api.autodesk.com/authentication/v1/authorize?response_type=code&client_id=YOURCLIENTID&redirect_uri=http%3A%2F%2FYOURcallbackURL&scope=data:read data:write bucket:create bucket:read data:create">Click here to grant access to your data!</a>
            </p>
          </div>

          <div class="mastfoot">
            <div class="inner">
              <p>Autodesk, Inc.</p>
            </div>
          </div>

        </div>

      </div>

    </div>

    <!-- Bootstrap core JavaScript
    ================================================== -->
    <!-- Placed at the end of the document so the pages load faster -->
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
  </body>
</html>

Our credentials that are connected to the API keys that we are currently using will be asked in order to authorize the web flow.

Once allowed, in the URL we will find the code=<YOURCODE> value. We will need this code in order to get our 3 legged authentication token. Now we will start with our first cURL call to obtain our token.

// cURL Call 3 legged token.

curl -v 'https://developer.api.autodesk.com/authentication/v1/gettoken' -X 'POST' -H 'Content-Type: application/x-www-form-urlencoded' -d 'client_id=xxxxxxxxxxxxMvsm6GiJNfAH5ozz&client_secret=xxxxxxxxxxxctH8nj&grant_type=authorization_code&code=GpcRL0R4GzPPjZm051CaJbRhw2hxxxxxxxxxxx&redirect_uri=http://jaimeblog.com/oauth/callback' | jq '.'

// Result
* Curl_http_done: called premature == 0
100   863  100   665  100   198   2488    740 --:--:-- --:--:-- --:--:--  2490
* Connection #0 to host developer.api.autodesk.com left intact
{
  "access_token": "xxxxxxxxxxxxxxxxxx.eyJ1c2VyaWQiOiJLMzdITEtTVUFKQUIiLCJleHAiOjE0OTAxMjIwOTYsInNjb3BlIjpbImRhdGE6d3JpdGUiLCJkYXRhOmNyZWF0ZSIsImRhdGE6cmVhZCIsImJ1Y2tldDpyZWFkIiwiYnVja2V0OmNyZWF0ZSJdLCJjbGllbnRfaWQiOiJ2d0xranBnN2JPR1VBdm5sTXZzbTZHaUpOZkFINW96eiIsImdyYW50X2lkIjoia09UN25YMjBYZmZuT1h5dUNWQjRmakZPRTYxeDBHenMiLCJhdWQiOiJodHRwczovL2F1dG9kZXNrLmNvbS9hdWQvand0ZXhwMTQ0MCIsImp0aSI6IlNFaVNTSTBaNkJGVVNQNkUzU1NRNFhXSVhKMzNjQ1hENG9UR2tNMjdkWWo4ZlFSejdnSmVVN3RmN3VRaTkyU2wifQ.hB43Oq3yBmJr_Rk7Y3OLWvGsxPT9xAcueA7iG46eFOU",
  "refresh_token": "xxxxxxxxxxxxxxxpkwuApegfpXbpa0De9YT24q50HY",
  "token_type": "Bearer",
  "expires_in": 86399
}

As you can see, the length of our tokens now have increased since we are getting JWT (JSON Web Token) now. See more about Forge and JWT here. 

In order to not have to copying and pasting the long length of our token in all subsequent calls, we will export it to one of our bash variables.

Type the following in your terminal

export FORGE_ACCESS_TOKEN=YOURTOKEN

Now we have stored the value of our token inside of a bash variable to be use in the rest of our calls.  The next step will be to obtain back a list of the available Hubs our user has access to it. You can check this from the UI of the Team services products and the BIM 360 Docs Projects your key has been registered with. Check here in case you missed the link reference above. 

//Step 1: Find the hub that has your resource

curl -X 'GET' -H 'Authorization: Bearer '$FORGE_ACCESS_TOKEN'' 'https://developer.api.autodesk.com/project/v1/hubs' | jq '.'
// Response 

{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": {
      "href": "https://developer.api.autodesk.com/project/v1/hubs"
    }
  },
  "data": [
    {
      "type": "hubs",
      "id": "a.YnVzaW5lc3M6YXV0b2xxxxxxxxx",
      "attributes": {
        "name": "autodesk",
        "extension": {
          "type": "hubs:autodesk.core:Hub",
          "version": "1.0",
          "schema": {
            "href": "https://developer.api.autodesk.com/schema/v1/versions/hubs:autodesk.core:Hub-1.0"
          },
          "data": {}
        }
      },
      "links": {
        "self": {
          "href": "https://developer.api.autodesk.com/project/v1/hubs/a.YnVzaW5lc3M6YXV0b2xxxxxxxxx"
        }
      },
      "relationships": {
        "projects": {
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/project/v1/hubs/a.YnVzaW5lc3M6YXV0b2xxxxxxxxx/projects"
            }
          }
        }
      }
    },
    {
      "type": "hubs",
      "id": "a.cGVyc29uYWw6dWUyOTxxxxxxxxx",
      "attributes": {
        "name": "jaime.rosales.duque",
        "extension": {
          "type": "hubs:autodesk.a360:PersonalHub",
          "version": "1.0",
          "schema": {
            "href": "https://developer.api.autodesk.com/schema/v1/versions/hubs:autodesk.a360:PersonalHub-1.0"
          },
          "data": {}
        }
      },
      "links": {
        "self": {
          "href": "https://developer.api.autodesk.com/project/v1/hubs/a.cGVyc29uYWw6dWUyOTxxxxxxxxx"
        }
      },
      "relationships": {
        "projects": {
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/project/v1/hubs/a.cGVyc29uYWw6dWUyOTxxxxxxxxx/projects"
            }
          }
        }
      }
    },
    {
      "type": "hubs",
      "id": "a.YnVzaW5lc3M6Yxxxxxxxxxx",
      "attributes": {
        "name": "DevTech AEC",
        "extension": {
          "type": "hubs:autodesk.core:Hub",
          "version": "1.0",
          "schema": {
            "href": "https://developer.api.autodesk.com/schema/v1/versions/hubs:autodesk.core:Hub-1.0"
          },
          "data": {}
        }
      },
      "links": {
        "self": {
          "href": "https://developer.api.autodesk.com/project/v1/hubs/a.YnVzaW5lc3M6Yxxxxxxxxxx"
        }
      },
      "relationships": {
        "projects": {
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/project/v1/hubs/a.YnVzaW5lc3M6Yxxxxxxxxxx/projects"
            }
          }
        }
      }
    },
    {
      "type": "hubs",
      "id": "b.e6d7a065-e57d-4abc-89c3-caf859bxxxxx",
      "attributes": {
        "name": "Autodesk2016-02-01 19:02:43 UTC",
        "extension": {
          "type": "hubs:autodesk.bim360:Account",
          "version": "1.0",
          "schema": {
            "href": "https://developer.api.autodesk.com/schema/v1/versions/hubs:autodesk.bim360:Account-1.0"
          },
          "data": {}
        }
      },
      "links": {
        "self": {
          "href": "https://developer.api.autodesk.com/project/v1/hubs/b.e6d7a065-e57d-4abc-89c3-caf859bxxxxx"
        }
      },
      "relationships": {
        "projects": {
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/project/v1/hubs/b.e6d7a065-e57d-4abc-89c3-caf859bxxxxx/projects"
            }
          }
        }
      }
    },
    {
      "type": "hubs",
      "id": "b.a4f95080-84fe-4281-8d0a-bd8c88xxxxxx",
      "attributes": {
        "name": "Autodesk2016-02-01 22:47:50 UTC",
        "extension": {
          "type": "hubs:autodesk.bim360:Account",
          "version": "1.0",
          "schema": {
            "href": "https://developer.api.autodesk.com/schema/v1/versions/hubs:autodesk.bim360:Account-1.0"
          },
          "data": {}
        }
      },
      "links": {
        "self": {
          "href": "https://developer.api.autodesk.com/project/v1/hubs/b.a4f95080-84fe-4281-8d0a-bd8c88xxxxxx"
        }
      },
      "relationships": {
        "projects": {
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/project/v1/hubs/b.a4f95080-84fe-4281-8d0a-bd8c88xxxxxx/projects"
            }
          }
        }
      }
    }
  ],
  "meta": {
    "warnings": [
      {
        "Id": null,
        "HttpStatusCode": "403",
        "ErrorCode": "BIM360DM_ERROR",
        "Title": "Unable to get hubs from BIM360DM EMEA.",
        "Detail": "You don't have permission to access this API",
        "AboutLink": null,
        "Source": [],
        "meta": []
      }
    ]
  }
}

As we can see in the response above, We get back all the HUBS in the Team Service that we are part of and also all the BIM 360 Docs ones, an easy and fast way to identify the BIM 360 Docs ones is by looking for the Id that begins with the letter "b"

This Id is similar to our account ID from the registration to the BIM 360 API Integration b.a4f95080-84fe-4281-8d0a-bd8c88xxxxxx.

//Step 2: Find the project that has your resource

curl -X GET -H 'Authorization: Bearer '$FORGE_ACCESS_TOKEN'' 'https://developer.api.autodesk.com/project/v1/hubs/b.a4f95080-84fe-4281-8d0a-bd8c88xxxxxx/projects' | jq '.'


//Response

{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": {
      "href": "https://developer.api.autodesk.com/project/v1/hubs/b.a4f95080-84fe-4281-8d0a-bd8c885695e0/projects"
    }
  },
  "data": [
    {
      "type": "projects",
      "id": "b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274",
      "attributes": {
        "name": "Docs Jaime access",
        "extension": {
          "type": "projects:autodesk.bim360:Project",
          "version": "1.0",
          "schema": {
            "href": "https://developer.api.autodesk.com/schema/v1/versions/projects:autodesk.bim360:Project-1.0"
          },
          "data": {}
        }
      },
      "links": {
        "self": {
          "href": "https://developer.api.autodesk.com/project/v1/hubs/b.a4f95080-84fe-4281-8d0a-bd8c88xxxxxx/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274"
        }
      },
      "relationships": {
        "hub": {
          "data": {
            "type": "hubs",
            "id": "b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274"
          },
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/project/v1/hubs/b.a4f95080-84fe-4281-8d0a-bd8c88xxxxxx"
            }
          }
        },
        "rootFolder": {
          "data": {
            "type": "folders",
            "id": "urn:adsk.wipprod:fs.folder:co.uQvUKg5SRiewt2ZjUrtmcg"
          },
          "meta": {
            "link": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.uQvUKg5SRiewt2ZjUrtmcg"
            }
          }
        },
        "topFolders": {
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/project/v1/hubs/b.a4f95080-84fe-4281-8d0a-bd8c88xxxxxx/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/topFolders"
            }
          }
        }
      }
    }
  ]
}

After getting the list of Projects successfully, we can pick one of the projects to create our storage location. But first lets get the list of Folders inside of our BIM 360 Docs Project available to Upload.

// Step 3: Get Folder 
// We pass in the ProjectID and the Root Folder ID in the following End Point.

curl -X GET -H 'Authorization: Bearer '$FORGE_ACCESS_TOKEN'' 'https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn%3Aadsk.wipprod%3Afs.folder%3Aco.uQvUKg5SRiewt2ZjUrtmcg/contents' | jq '.'

// Response

{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": {
      "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.uQvUKg5SRiewt2ZjUrtmcg/contents"
    }
  },
  "data": [
    {
      "type": "folders",
      "id": "urn:adsk.wipprod:fs.folder:co.4Gx-9UIlRb-0SQrMr37tjw",
      "attributes": {
        "name": "Photos",
        "displayName": "Photos",
        "createTime": "2017-04-11T17:33:32.0000000Z",
        "createUserId": "",
        "createUserName": "",
        "lastModifiedTime": "2017-04-11T17:33:32.0000000Z",
        "lastModifiedUserId": "",
        "lastModifiedUserName": "",
        "objectCount": 0,
        "hidden": false,
        "extension": {
          "type": "folders:autodesk.bim360:Folder",
          "version": "1.0",
          "schema": {
            "href": "https://developer.api.autodesk.com/schema/v1/versions/folders:autodesk.bim360:Folder-1.0"
          },
          "data": {
            "allowedTypes": [
              "items:autodesk.bim360:File",
              "folders:autodesk.bim360:Folder"
            ],
            "visibleTypes": [
              "items:autodesk.bim360:File"
            ]
          }
        }
      },
      "links": {
        "self": {
          "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.4Gx-9UIlRb-0SQrMr37tjw"
        }
      },
      "relationships": {
        "contents": {
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.4Gx-9UIlRb-0SQrMr37tjw/contents"
            }
          }
        },
        "parent": {
          "data": {
            "type": "folders",
            "id": "urn:adsk.wipprod:fs.folder:co.uQvUKg5SRiewt2ZjUrtmcg"
          },
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.4Gx-9UIlRb-0SQrMr37tjw/parent"
            }
          }
        },
        "refs": {
          "links": {
            "self": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.4Gx-9UIlRb-0SQrMr37tjw/relationships/refs"
            },
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.4Gx-9UIlRb-0SQrMr37tjw/refs"
            }
          }
        },
        "links": {
          "links": {
            "self": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.4Gx-9UIlRb-0SQrMr37tjw/relationships/links"
            }
          }
        }
      }
    },
    {
      "type": "folders",
      "id": "urn:adsk.wipprod:fs.folder:co.7ISq_WHERfKOfShXZDFDYw",
      "attributes": {
        "name": "Plans",
        "displayName": "Plans",
        "createTime": "2017-04-11T17:33:32.0000000Z",
        "createUserId": "",
        "createUserName": "",
        "lastModifiedTime": "2017-04-17T18:06:45.0000000Z",
        "lastModifiedUserId": "TNSUM9VPW79S",
        "lastModifiedUserName": "Jaime%20Rosales",
        "objectCount": 5,
        "hidden": false,
        "extension": {
          "type": "folders:autodesk.bim360:Folder",
          "version": "1.0",
          "schema": {
            "href": "https://developer.api.autodesk.com/schema/v1/versions/folders:autodesk.bim360:Folder-1.0"
          },
          "data": {
            "allowedTypes": [
              "folders:autodesk.bim360:Folder",
              "items:autodesk.bim360:File",
              "items:autodesk.bim360:Document",
              "items:autodesk.bim360:TitleBlock",
              "items:autodesk.bim360:ReviewDocument"
            ],
            "actions": [
              "CONVERT",
              "SPLIT",
              "OCR"
            ],
            "visibleTypes": [
              "items:autodesk.bim360:Document"
            ]
          }
        }
      },
      "links": {
        "self": {
          "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.7ISq_WHERfKOfShXZDFDYw"
        }
      },
      "relationships": {
        "contents": {
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.7ISq_WHERfKOfShXZDFDYw/contents"
            }
          }
        },
        "parent": {
          "data": {
            "type": "folders",
            "id": "urn:adsk.wipprod:fs.folder:co.uQvUKg5SRiewt2ZjUrtmcg"
          },
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.7ISq_WHERfKOfShXZDFDYw/parent"
            }
          }
        },
        "refs": {
          "links": {
            "self": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.7ISq_WHERfKOfShXZDFDYw/relationships/refs"
            },
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.7ISq_WHERfKOfShXZDFDYw/refs"
            }
          }
        },
        "links": {
          "links": {
            "self": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.7ISq_WHERfKOfShXZDFDYw/relationships/links"
            }
          }
        }
      }
    },
    {
      "type": "folders",
      "id": "urn:adsk.wipprod:fs.folder:co.pZoSnUcoR1eJQu_PRyvfeg",
      "attributes": {
        "name": "Project Files",
        "displayName": "Project Files",
        "createTime": "2017-04-11T17:33:33.0000000Z",
        "createUserId": "",
        "createUserName": "",
        "lastModifiedTime": "2017-04-11T17:33:33.0000000Z",
        "lastModifiedUserId": "",
        "lastModifiedUserName": "",
        "objectCount": 0,
        "hidden": false,
        "extension": {
          "type": "folders:autodesk.bim360:Folder",
          "version": "1.0",
          "schema": {
            "href": "https://developer.api.autodesk.com/schema/v1/versions/folders:autodesk.bim360:Folder-1.0"
          },
          "data": {
            "allowedTypes": [
              "items:autodesk.bim360:File",
              "folders:autodesk.bim360:Folder"
            ],
            "actions": [
              "CONVERT"
            ],
            "visibleTypes": [
              "items:autodesk.bim360:File"
            ]
          }
        }
      },
      "links": {
        "self": {
          "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.pZoSnUcoR1eJQu_PRyvfeg"
        }
      },
      "relationships": {
        "contents": {
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.pZoSnUcoR1eJQu_PRyvfeg/contents"
            }
          }
        },
        "parent": {
          "data": {
            "type": "folders",
            "id": "urn:adsk.wipprod:fs.folder:co.uQvUKg5SRiewt2ZjUrtmcg"
          },
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.pZoSnUcoR1eJQu_PRyvfeg/parent"
            }
          }
        },
        "refs": {
          "links": {
            "self": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.pZoSnUcoR1eJQu_PRyvfeg/relationships/refs"
            },
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.pZoSnUcoR1eJQu_PRyvfeg/refs"
            }
          }
        },
        "links": {
          "links": {
            "self": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.pZoSnUcoR1eJQu_PRyvfeg/relationships/links"
            }
          }
        }
      }
    },
    {
      "type": "folders",
      "id": "urn:adsk.wipprod:fs.folder:co.OXRxgLMvSQWdQW_ILyF4OQ",
      "attributes": {
        "name": "ProjectTb",
        "displayName": "ProjectTb",
        "createTime": "2017-04-11T17:33:33.0000000Z",
        "createUserId": "",
        "createUserName": "",
        "lastModifiedTime": "2017-04-17T18:09:22.0000000Z",
        "lastModifiedUserId": "TNSUM9VPW79S",
        "lastModifiedUserName": "Jaime%20Rosales",
        "objectCount": 1,
        "hidden": false,
        "extension": {
          "type": "folders:autodesk.bim360:Folder",
          "version": "1.0",
          "schema": {
            "href": "https://developer.api.autodesk.com/schema/v1/versions/folders:autodesk.bim360:Folder-1.0"
          },
          "data": {
            "allowedTypes": [
              "items:autodesk.bim360:TitleBlock"
            ]
          }
        }
      },
      "links": {
        "self": {
          "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.OXRxgLMvSQWdQW_ILyF4OQ"
        }
      },
      "relationships": {
        "contents": {
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.OXRxgLMvSQWdQW_ILyF4OQ/contents"
            }
          }
        },
        "parent": {
          "data": {
            "type": "folders",
            "id": "urn:adsk.wipprod:fs.folder:co.uQvUKg5SRiewt2ZjUrtmcg"
          },
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.OXRxgLMvSQWdQW_ILyF4OQ/parent"
            }
          }
        },
        "refs": {
          "links": {
            "self": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.OXRxgLMvSQWdQW_ILyF4OQ/relationships/refs"
            },
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.OXRxgLMvSQWdQW_ILyF4OQ/refs"
            }
          }
        },
        "links": {
          "links": {
            "self": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.OXRxgLMvSQWdQW_ILyF4OQ/relationships/links"
            }
          }
        }
      }
    }
  ]
}

If you have a subfolder you will like to to the upload, you can repeat the step above by exploring the content of the folder where you have the subfolder by replacing the Folder ID with the location where it is. 

One thing to keep in mind is the Type of Supported data every Folder contains, For Example the selected one for us in this case will be the Project File folder which contains the following data. 

"data": {
            "allowedTypes": [
              "items:autodesk.bim360:File",
              "folders:autodesk.bim360:Folder"
            ],
            "actions": [
              "CONVERT"
            ],
            "visibleTypes": [
              "items:autodesk.bim360:File"
            ]
          }

Which this means is, that only Files and Folders can be uploaded to it and the only visible part will be the complete file, since the action to be performed at the time of upload will Convert to SVF. 

If we select Plans folder, this will be the available data. 

"data": {
            "allowedTypes": [
              "folders:autodesk.bim360:Folder",
              "items:autodesk.bim360:File",
              "items:autodesk.bim360:Document",
              "items:autodesk.bim360:TitleBlock",
              "items:autodesk.bim360:ReviewDocument"
            ],
            "actions": [
              "CONVERT",
              "SPLIT",
              "OCR"
            ],
            "visibleTypes": [
              "items:autodesk.bim360:Document"
            ]
}

Where we have more options of convertion of our uploaded file, this is the reason why, when we upload a Revit file containing 2D sheets, the file gets split and you have access to every single file individually. Something to keep in mind. 

 

Now we will move forward to create our storage location. We will need to pass the Project and Folder ID respectively to the following end point. Make sure you pass in the values that are asked in the following call.

//Step 4: Create a storage location

curl -X POST -H "Content-Type: application/vnd.api+json" -H "Accept: application/vnd.api+json" -H 'Authorization: Bearer '$FORGE_ACCESS_TOKEN'' -d '{
      "jsonapi": { "version": "1.0" },
      "data": {
        "type": "objects",
        "attributes": {
          "name": "Studio Apartment.rvt"
        },
        "relationships": {
          "target": {
            "data": { "type": "folders", "id": "urn:adsk.wipprod:fs.folder:co.7ISq_WHERfKOfShXZDFDYw" }
          }
        }
      }
}' "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/storage" | jq '.'

// Response

{
  "jsonapi": {
    "version": "1.0"
  },
  "data": {
    "type": "objects",
    "id": "urn:adsk.objects:os.object:wip.dm.prod/633fc6c2-xxxx-xxxx-xxxx-3db6e54d7ef4.pdf",
    "relationships": {
      "target": {
        "data": {
          "type": "folders",
          "id": "urn:adsk.wipprod:fs.folder:co.pZoSnUcoR1eJQu_PRyvfeg"
        },
        "links": {
          "related": {
            "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/folders/urn:adsk.wipprod:fs.folder:co.pZoSnUcoR1eJQu_PRyvfeg"
          }
        }
      }
    }
  }
}

In the above examples, make note of the the object ID, project ID and folder ID which are respectively. The POST projects/:project_id/items endpoint creates the first version of the uploaded file. 

Let's upload our file 

//Step 4: Upload a file to the storage location

curl -X PUT -H 'Authorization: Bearer '$FORGE_ACCESS_TOKEN'' --data-binary @Studio Apartment.rvt 'https://developer.api.autodesk.com/oss/v2/buckets/wip.dm.prod/objects/acecf083-a567-4cef-9873-d2842e52c725.rvt' | jq '.'

//Response
{
  "bucketKey": "wip.dm.prod",
  "objectId": "urn:adsk.objects:os.object:wip.dm.prod/633fc6c2-4e05-4636-b4be-3db6e54d7ef4.rvt",
  "objectKey": "633fc6c2-4e05-4636-b4be-3db6e54d7ef4.rvt",
  "sha1": "e397fb8b627c9fc6c5d71ae2f87eeb7c6ebbe8d6",
  "size": 69120,
  "contentType": "application/x-www-form-urlencoded",
  "location": "https://developer.api.autodesk.com/oss/v2/buckets/wip.dm.prod/objects/633fc6c2-4e05-4636-b4be-3db6e54d7ef4.rvt"
}

And now finally let's create the 1st version of our recently uploaded file. 

//Step 5: Create the first version of the uploaded file


curl -X POST -H 'Authorization: Bearer '$FORGE_ACCESS_TOKEN'' -H "Content-Type: application/vnd.api+json" -d '{
    "jsonapi": { "version": "1.0" },
    "data": {
      "type": "items",
      "attributes": {
        "displayName": "Studio Apartment.rvt",
        "extension": {
          "type": "items:autodesk.bim360:File",
          "version": "1.0"
        }
      },
      "relationships": {
        "tip": {
          "data": {
            "type": "versions", "id": "1"
          }
        },
        "parent": {
          "data": {
            "type": "folders",
            "id": "urn:adsk.wipprod:fs.folder:co.7ISq_WHERfKOfShXZDFDYw"
          }
        }
      }
    },
    "included": [
      {
        "type": "versions",
        "id": "1",
        "attributes": {
          "name": "Studio Apartment.rvt",
          "extension": {
            "type": "versions:autodesk.bim360:File",
            "version": "1.0"
          }
        },
        "relationships": {
          "storage": {
            "data": {
              "type": "objects",
              "id": "urn:adsk.objects:os.object:wip.dm.prod/acecf083-a567-4cef-9873-d2842e52c725.rvt"
            }
          }
        }
      }
    ]
  }' "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/items" | jq '.'



// Response 

{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": {
      "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/items/urn:adsk.wipprod:dm.lineage:4BzS92I5R4Sul0No_BOoVg"
    }
  },
  "data": {
    "type": "items",
    "id": "urn:adsk.wipprod:dm.lineage:4BzS92I5R4Sul0No_BOoVg",
    "attributes": {
      "displayName": "Studio Apartment.rvt",
      "createTime": "2017-06-06T17:54:30.0000000Z",
      "createUserId": "TNSUM9VPW79S",
      "createUserName": "Jaime Rosales Duque",
      "lastModifiedTime": "2017-06-06T17:54:30.0000000Z",
      "lastModifiedUserId": "TNSUM9VPW79S",
      "lastModifiedUserName": "Jaime Rosales Duque",
      "hidden": false,
      "extension": {
        "type": "items:autodesk.bim360:File",
        "version": "1.0",
        "schema": {
          "href": "https://developer.api.autodesk.com/schema/v1/versions/items:autodesk.bim360:File-1.0"
        },
        "data": {}
      }
    },
    "links": {
      "self": {
        "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/items/urn:adsk.wipprod:dm.lineage:4BzS92I5R4Sul0No_BOoVg"
      }
    },
    "relationships": {
      "tip": {
        "data": {
          "type": "versions",
          "id": "urn:adsk.wipprod:fs.file:vf.4BzS92I5R4Sul0No_BOoVg?version=1"
        },
        "links": {
          "related": {
            "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/items/urn:adsk.wipprod:dm.lineage:4BzS92I5R4Sul0No_BOoVg/tip"
          }
        }
      },
      "versions": {
        "links": {
          "related": {
            "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/items/urn:adsk.wipprod:dm.lineage:4BzS92I5R4Sul0No_BOoVg/versions"
          }
        }
      },
      "parent": {
        "data": {
          "type": "folders",
          "id": "urn:adsk.wipprod:fs.folder:co.pZoSnUcoR1eJQu_PRyvfeg"
        },
        "links": {
          "related": {
            "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/items/urn:adsk.wipprod:dm.lineage:4BzS92I5R4Sul0No_BOoVg/parent"
          }
        }
      },
      "refs": {
        "links": {
          "self": {
            "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/items/urn:adsk.wipprod:dm.lineage:4BzS92I5R4Sul0No_BOoVg/relationships/refs"
          },
          "related": {
            "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/items/urn:adsk.wipprod:dm.lineage:4BzS92I5R4Sul0No_BOoVg/refs"
          }
        }
      },
      "links": {
        "links": {
          "self": {
            "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/items/urn:adsk.wipprod:dm.lineage:4BzS92I5R4Sul0No_BOoVg/relationships/links"
          }
        }
      }
    }
  },
  "included": [
    {
      "type": "versions",
      "id": "urn:adsk.wipprod:fs.file:vf.4BzS92I5R4Sul0No_BOoVg?version=1",
      "attributes": {
        "name": "Studio Apartment.rvt",
        "displayName": "Studio Apartment.rvt",
        "createTime": "2017-06-06T17:54:30.0000000Z",
        "createUserId": "TNSUM9VPW79S",
        "createUserName": "Jaime Rosales Duque",
        "lastModifiedTime": "2017-06-06T17:54:30.0000000Z",
        "lastModifiedUserId": "TNSUM9VPW79S",
        "lastModifiedUserName": "Jaime Rosales Duque",
        "versionNumber": 1,
        "storageSize": 69120,
        "fileType": "pdf",
        "extension": {
          "type": "versions:autodesk.bim360:File",
          "version": "1.0",
          "schema": {
            "href": "https://developer.api.autodesk.com/schema/v1/versions/versions:autodesk.bim360:File-1.0"
          },
          "data": {}
        }
      },
      "links": {
        "self": {
          "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/versions/urn:adsk.wipprod:fs.file:vf.4BzS92I5R4Sul0No_BOoVg%3Fversion=1"
        }
      },
      "relationships": {
        "item": {
          "data": {
            "type": "items",
            "id": "urn:adsk.wipprod:dm.lineage:4BzS92I5R4Sul0No_BOoVg"
          },
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/versions/urn:adsk.wipprod:fs.file:vf.4BzS92I5R4Sul0No_BOoVg%3Fversion=1/item"
            }
          }
        },
        "links": {
          "links": {
            "self": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/versions/urn:adsk.wipprod:fs.file:vf.4BzS92I5R4Sul0No_BOoVg%3Fversion=1/relationships/links"
            }
          }
        },
        "refs": {
          "links": {
            "self": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/versions/urn:adsk.wipprod:fs.file:vf.4BzS92I5R4Sul0No_BOoVg%3Fversion=1/relationships/refs"
            },
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/versions/urn:adsk.wipprod:fs.file:vf.4BzS92I5R4Sul0No_BOoVg%3Fversion=1/refs"
            }
          }
        },
        "downloadFormats": {
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/b.ab37405e-xxxx-xxxx-xxxx-7a1a681d3274/versions/urn:adsk.wipprod:fs.file:vf.4BzS92I5R4Sul0No_BOoVg%3Fversion=1/downloadFormats"
            }
          }
        },
        "derivatives": {
          "data": {
            "type": "derivatives",
            "id": "dXJuOmFkc2sud2lwcHJvZDpmcy5maWxlOnZmLjRCelM5Mkk1UjRTdWwwTm9fQk9vVmc_dmVyc2lvbj0x"
          },
          "meta": {
            "link": {
              "href": "https://developer.api.autodesk.com/modelderivative/v2/designdata/dXJuOmFkc2sud2lwcHJvZDpmcy5maWxlOnZmLjRCelM5Mkk1UjRTdWwwTm9fQk9vVmc_dmVyc2lvbj0x/manifest"
            }
          }
        },
        "thumbnails": {
          "data": {
            "type": "thumbnails",
            "id": "dXJuOmFkc2sud2lwcHJvZDpmcy5maWxlOnZmLjRCelM5Mkk1UjRTdWwwTm9fQk9vVmc_dmVyc2lvbj0x"
          },
          "meta": {
            "link": {
              "href": "https://developer.api.autodesk.com/modelderivative/v2/designdata/dXJuOmFkc2sud2lwcHJvZDpmcy5maWxlOnZmLjRCelM5Mkk1UjRTdWwwTm9fQk9vVmc_dmVyc2lvbj0x/thumbnail"
            }
          }
        },
        "storage": {
          "data": {
            "type": "objects",
            "id": "urn:adsk.objects:os.object:wip.dm.prod/633fc6c2-4e05-4636-b4be-3db6e54d7ef4.rvt"
          },
          "meta": {
            "link": {
              "href": "https://developer.api.autodesk.com/oss/v2/buckets/wip.dm.prod/objects/633fc6c2-4e05-4636-b4be-3db6e54d7ef4.rvt"
            }
          }
        }
      }
    }
  ]
}

Now if we check our BIM 360 Docs UI we will be able to see the recent uploaded and translated file. 

Hope this insight helps you with your development with Data Management API and the access to BIM 360 Docs, tweet me if you have any questions.

Cheers, and until next time. 

Posts by author

Jaime Rosales
Sr. Developer Consultant