Prompted by an inquiry through the forum post, I made a minimum sample that uses HQ API. I wanted to do “Intro Labs” series for Forge API for a while any way. He gave me a little push to start something along the line of Intro Labs. (So thank you for asking.) Not quite to the level of Labs, yet. I hope I will be accumulating how-to materials as I write in small chunks at a time.
The Intro sample is intended for people who is new to HQ API. The sample demonstrates the following workflow:
- Get a token using two-legged authentication
- Get the list of companies
- Updates a company info
Following REST calls are used in the sample:
- POST authentication/v1/authenticate
- GET hq/v1/accounts/:account_id/companies
- PATCH hq/v1/accounts/:account_id/companies/:company_id
Note that currently HQ API supports two-legged authentication only. Three-legged does not work with HQ API.
Before we dive into programming, however, there are important steps that you need to go through; i.e., exchange of your developer key and account ID in the Account Settings page of your BIM 360 account or bim360enterprise.autodesk.com.
- Go to the developer portal developer.autodesk.com. Sign-up as a developer or sign-in if you already have an Autodesk ID. Create an app, and save the client id and secret. (When you are on Create App page, you will see CallBack URL. For HQ API, it can be anything as two-legged authentication does not use callback.)
- Log into BIM 360 Enterprise: https://bim360enterprise.autodesk.com/. Go to “i” (“Account Settings” menu). Go to “Apps & Integrations”. Add your app there. Keep a note of account id.
For more detail about developer portal, please take a look at the following page, which has step-by-step instruction on creating/registering an app:
My earlier post talks about registering your app in BIM 360 Enterprise.
HQ API Intro App
Once you have set the above, you are ready to use API’s. Below shows the image of the UI from the sample app.
What it does is quite simple:
- [Get Token] button makes a /authenticate call to get a two-legged token.
- You will need to manually enter the account id (the second text box from the top).
- [Companies] button makes a /companies call to get a list of companies. The list of company names are filled in as a pull down selection (the third text box from the top).
- [Data] button displays data for the currently selected company as formatted text (like shown in the above image).
- Enter the new data in the fourth text box. (You can copy and paste a portion of company data displayed in Response/Data text box and modify them in a way you want.
For example, in the above image, I’m trying to change the “erp_id” from “123” to “123-456-789”, and about press [Update] button.
You can download the source code from here.
The project is minimum for clarity and focusing on understanding the logic of HQ API for learning purposes. In practice, you will not display token. You probably keep it on the server side. I used Microsoft Visual Studio 2015 with Node.js and Express 3. You may need to install “Node.js tools for Visual Studio” if you don’t have it, yet.
I would also note that you should always keep client-id and secret on the server side, and not in the client side.
- “Forge Hackathon: Introduction to BIM 360” – webcast recording from Forge Hackathon 2016. This basically talks about HQ API.
- “DevCon 2016: Integrate & Extend Your Construction Ecosystem with BIM360 API & Forge“. Slides from DevCon 2016 class by Keith White and Saikat Bhattacharya. This includes HQ API as a part of topic.
- HQ API documentation on developer.autodesk.com.
I intend to update and add more details as I go along. But for now, sharing what I have.