中文链接

By Aaron Lu

BIM 360 Glue API

Before developing application based on BIM 360 API, tools can help us to have a better understanding of RESFful API.

I’m going to use cURL and Postman to demonstrate how to call Glue API to login and query project list.

Login

Before login, we need to apply the API key and secret, if you don’t know what are they, please contact ADN to apply.

After login, server will return an auth_token which is used for future API calls to replace api secret as authentication information. So auth_token is very important, once the it is stolen, other developers can do harm to your project, so we need to protect it carefully.

Login is a POST request sent to https://b4.autodesk.com/api/security/v1/login.{format}, here {format} designates the format of return data. Glue API supports json and xml format. the POST content must contain the following parameters (other optional parameters is not listed here, refer to API document for more information):

Parameter	Meaning
login_name	Login name, i.e. Autodsek Id
password	Password
company_id	Company ID
api_key	API key
api_secret	API secret
timestamp	A timestamp, which is a number of seconds representing current time
sig	A md5 string, calculated from combined string of api_key, api_secret and timestamp

The last 2 parameters, timestamp and sig, are needed by almost all API calls, and vary by time.

See more about how to Calcuate timestamp and sig.

In this post, we will use json format, so the target url should be: https://b4.autodesk.com/api/security/v1/login.json

Method is: POST

Post content:

login_name=Aaron.Lu@autodesk.com
&company_id=adn
&password=********
&api_key=fe251558432bd3da0a70326ed169****
&api_secret=70aadb2838cac9a739da11296d7f****
&timestamp=1428647796
&sig=6ec77c0448fcb16da9c1f03220a96ceb

using cURL command:

Type following command at the prompt and press Enter:

curl --data "login_name=Aaron.Lu@autodesk.com
&company_id=adn&password=********
&api_key=fe251558432bd3da0a70326ed169****
&api_secret=70aadb2838cac9a739da11296d7f****
&timstamp=1428647796
&sig=6ec77c0448fcb16da9c1f03220a96ceb" https://b4.autodesk.com/api/security/v1/login.json

–data  means we are going to send data with POST method.

Following is the return result:

{"auth_token":"35730ba86d48470593c1e63090610aa5",
"user_id":"****0b93-e919-****-9695-8b3733fa****",
"account_id":"****a18f-****-4b8a-****-8d762595****",
"account_hostname":"adn"}

NOTE: save the auth_token, we will use it later.

using PostMan

Choose method POST，fill form-data with parameters and values, click “Send”, same result will show under “Body”:

Get project list

The url is https://b4.autodesk.com/api/project/v1/list.{format}

Method: GET

Parameter:

Parameter	Meaning
company_id	Company ID
api_key	API key
timestamp	A timestamp, which is a number of seconds representing current time
sig	A md5 string, calculated from combined string of api_key, api_secret and timestamp
auth_token	a hash, returned by server after login successfully

as we can see, api_secret, login_name and password are not needed, instead, auth_token is used.

Since we are using GET method, all the parameters should be included in the url, so the final url is:

https://b4.autodesk.com/api/project/v1/list.json?company_id=adn &api_key=fe251558432bd3da0a70326ed169**** &timestamp=1428650893 &sig=8d22b59569335394d7b219aae91990a7 &auth_token=34dd71d838674c86a02da2fe329db24d

using cURL

Type following command at the prompt and press Enter:

curl https://b4.autodesk.com/api/project/v1/list.json
?company_id=adn
&api_key=fe251558432bd3da0a70326ed169****
&timstamp=1428650893
&sig=8d22b59569335394d7b219aae91990a7
&auth_token=34dd71d838674c86a02da2fe329db24d

Return result:

{
"project_list": [
{
"recent_model_info": [],
"project_id": "1e7e5e8d-fea8-49cd-8e5b-76058f0ee3b6",
"project_name": "AL+Sample+Project",
"company_id": "adn",
"created_date": "2015-03-19 03:26:51",
"modify_date": "2015-04-01 07:15:15",
"cmic_company_code": "",
"cmic_project_code": "",
"cw_project_code": "",
"thumbnail_modified_date": "2015-03-19 04:41:45",
"has_views": false,
"has_markups": false,
"has_clashes": false,
"has_points": false,
"total_member_count": 0,
"total_project_admin_count": 0,
"total_views_count": 0,
"total_markups_count": 0,
"last_activity_date": "2015-04-01 07:15:15",
"permissions": [],
"navisworks_version": "Nwd2014"
}
],
"page": 1,
"page_size": 1,
"total_result_size": 1,
"more_pages": 0
}

using PostMan

Choose GET, input url address, and click “Send”, we can see the result in the bottom.

Calculate timestamp and sig

timestamp

timestamp is a integer, UNIXEpoch Time, quote from wikipedia:

Unix time (also known as POSIX time or Epoch time) is a system for describing instants in time, defined as the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970, [note 1] not counting leap seconds.

Pseudo code looks like this:

Seconds(CurrentTime-1970/1/1)

Following are the ways of getting timestamp in multiple platforms:

Powershell (Windows 7 advanced command propmt, input Powershell in windows search dialog you can find the application. Since we want to use cURL and command line to call API, we use Powershell for convinience)

$oriDate=Get-Date -Date "01/01/1970"
$nowDate=(Get-Date).ToUniversalTime()
$timestamp=[int](New-TimeSpan -Start $oriDate -End $nowDate)
.TotalSeconds

C#

TimeSpan tSpan = (DateTime.UtcNow - new DateTime(1970, 1, 1));
int timestamp = (int)tSpan.TotalSeconds;

Node.js/Javascript

var timestamp = Math.floor((new Date).getTime()/1000);

Java

long timestamp = System.currentTimeMillis() / 1000L;

sig

sig is a md5, lower case string, without any dash (-), Glue API needs the md5 calculated from combination string of api_key, auth_token and timestamp. Pseudo code:

MD5 (api_key+auth_token+timestamp)

 

Following are how to get sig with multiple platforms:

Powershell

$identityString = $api_key + $api_secret + $timestamp
# compute hash
$md5 = new-object -TypeName System.Security.Cryptography
.MD5CryptoServiceProvider
$utf8 = new-object -TypeName System.Text.UTF8Encoding
$signature = [System.BitConverter]::ToString($md5.ComputeHash(
$utf8.GetBytes($identityString))).Replace("-","").ToLower()

C#

// using System.Security.Cryptography;
public string ComputeMD5Hash(string identityString)
{
// step 1, calculate MD5 hash from identityString
MD5 md5 = System.Security.Cryptography.MD5.Create();
byte[] inputBytes = System.Text.Encoding.UTF8.GetBytes(
identityString);
byte[] hash = md5.ComputeHash(inputBytes);
// step 2, convert byte array to hex string
StringBuilder sb = new StringBuilder();
for (int i = 0; i < hash.Length; i++)
{
sb.Append(hash[i].ToString("x2"));
}
return sb.ToString();
}

Node.js/Javascript

var crypto = require('crypto');
var hash = crypto.createHash('md5').update(identityString)
.digest("hex");

Java

public String computeMD5Hash(String identityString) {
java.security.MessageDigest md = java.security.MessageDigest
.getInstance("MD5");
byte[] array = md.digest(identityString.getBytes());
StringBuffer sb = new StringBuffer();
for (int i = 0; i < array.length; ++i) {
sb.append(Integer.toHexString((array[i] & 0xFF) | 0x100)
.substring(1,3));
}
return sb.toString();
}

Trouble shooting

If we see below problem, it probably caused by using wrong HTTP method, e.g. when it requires GET, but we are using POST.

<body>
<div id="content">
<p class="heading1">Service</p>
<p>Method not allowed.</p>
</div>
</body>