BIM 360 SDK: Part 1- BIM 360 Field API
BIM 360 SDK: Part 3 - BIM 360 Viewer Component

BIM 360 SDK: Part 2 - BIM 360 Glue API

BIM 360 Glue transforms BIM collaboration by helping to simplify multi‐discipline model coordination, clash detection, and providing mobile access to all project stakeholders. The extended project team can better coordinate and communicate with one-click access to review the latest project models and run clashes in real-time, promoting time and money savings on customer projects. 

  

BIM 360 Glue REST API

Glue’s REST API provides a RESTful interface that returns JSON or XML. It is essentially a data access API allowing developers to query and modify various data objects. Developers can integrate external applications such as project management systems, accounting systems or custom developed solutions with the BIM 360 platform. 
BIM-360-Glue-REST-API
BIM 360 Glue Web Services Architecture

Basic structure of a BIM 360 Glue API request and response follows the REST principles

  • The HTTP/HTTPS request (POST or GET) is made by client (POST/GET defined by the particular service call) 
  • Required parameters are sent to the server for the authentication and request
  • An example endpoint URL for a login request would be: http://b4.autodesk.com/api/security/v1/login.json
  • The server responds with an HTTP Status of 200 for success and appropriate code for failures
REST, short for REpresentational State Transfer is a set of principles that define how Web standards, such as HTTP and URIs, are supposed to be used for implementing heterogenous application to application communication. In short, REST provides a means for web-based communication focusing on shared understanding of data types, but limiting the scope of what is revealed to a standardized interface. If you want to learn more about REST architecture, refer Roy Fielding's dissertation describing REST or browse through the many good articles available on web.
Today most web and social platforms, including Twitter and the various services by Google, Facebook, etc. provide a RESTful interface for developers to interact with their platforms. Explore twitter api, or console of all google api

Google Maps APIAutodesk Inc., 1 Market St., San Francisco.

The example figure here shows how to make a webservice call to the google maps api and put a marker on a specific location in the map.    

Webservice Request <http://maps.googleapis.com/maps/api/staticmap?center=San+francisco&zoom=11&maptype=hybrid&size=400x250&markers=color:green%7Clabel:A%7C37.789018,-122.39150&visual_refresh=true&key=<apikey>&sensor=false>

As part of its 360 cloud services and platform - Autodesk 360, we offer various APIs such as the PLM 360 REST API for interacting with the PLM platform and connecting your custom apps, or the ReCap API that enables users to capture and integrate reality directly into your design process. The future of infrastructure modeling is about to be re-defined with the introduction of REST webservices and Infraworks 360 Pro.

The Web Services API  will allow third party developers to access to the various data objects within the BIM 360 Glue Platform. These data objects would include types such as Users, Projects, Models, etc. With this API, a developer could easily integrate external applications such as project management systems, accounting systems or custom developed solutions. 

BIM 360 Glue API Service Groups

The Web Services API is logically grouped into several Service Groups. The breakdown of the Service Groups is as follows:

  Bim-360-webservice-groups

The Glue Development Site would be a good place to start. For a complete list of web service calls, please refer to the Glue API documentation. Before starting to develop on BIM 360 Glue platform, you need to request a unique API key and Secret to be issued to you. (Please send us an email if you are interested). All Web Service calls to the Glue server should follow https://{base_URL}/{API_endpoint}.{format}?{required_parameters}&{optional_parameters>}

To illustrate an example, the base URL can be b4.autodesk.com/api for accessing the production BIM 360 Glue environment. API endpoints are defined as part of the webservice groups to interact with specific object types such as model, project, actions, etc. For login purposes, the end point is security/v1/login, where security is the group, v1 is the version of the method, and login is the specific call. The format parameter is the format of the response and it can be json or xml

The required parameters include a company_id, api key, timestamp, and a unique signature, in addition to the user's login name and password. The company_id refers to the instance or host of Glue account you are accessing and the unique signature is a way for Glue server to trust the web service call. To build the unique signature, concatenate the following information (api_key + api_secret + timestamp) and then generate the MD5 hash for the string. The Glue Platform validates the signature for every call to insure integrity of API transactions. On successful authentication an auth_token is returned by the server. All subsequent calls to the server should include this auth_token in addition to the other required parameters. Please take a look at the Glue API samples posted on this webpage to get a better understanding of making these webervice calls.

Project Listing API Request

This call returns a project listing from the BIM 360 Glue Platform. By default, it returns all of the projects for the selected company, or the project information for a given user, specified by user_id or login_name.

            -format
            -company_id
            -api_key
            -timestamp
            -signature (sig)
            -auth_token (obtained from login) 
 
Sample JSON response:

Below is the sample code written in C# that illustrates the above web service call

Similary, you can also interact with the Models, Users, and other types of objects that are accessible through the APIs. 

Error Handling / HTTP Status Code
The HTTP Status Code is the error handling mechanism for the Glue API. The server responds with 200 for successful operations and the appropriate HTTP Status code for errors. On success, the payload response is defined for each particular service call. For failures (i.e. non 200 HTTP status codes) , the payload is defined as a single text line with the additional information about error condition in the following format:

ERROR;401;You have specified invalid login credentials for the Glue Platform.

The following are typical error codes returned by the Web Service API:
-400 Bad Request
The request could not be understood by the server due to malformed / incorrect syntax being sent to the server
-401 Unauthorized
The request requires user authentication and the authentication / signature that was sent is invalid
-403 Forbidden
The server understood the request, but is refusing to fulfill it
-405 Method Not Allowed
The method specified in the Request-Line is not allowed for the resource identified by the Request-URI
-500 - Internal Server Error
There is a systems problem. Please contact Autodesk Technical Support to investigate
-503 Service Unavailable
The server is currently unavailable (because it is overloaded or down for maintenance)
Glue-activities-list
BIM 360 Glue Action API Sample

BIM 360 Glue Actions (Activities)

The Glue Platform stores information about many user interactions within the system. These operations are referred to as “Actions”
Typical Actions would be:
  • Uploading a Model
  • Creating a View on a Model
  • Adding Mark Up to a Model
  • Creating a Clash report for a Model
The Glue Web Services API returns many of these actions in API responses.  It can be used to create an audit trail or activity list to make the project more social and collaborative as shown in the image here. The Action API Service can be leveraged to develop exciting and intelligent applications for data analytics and analysis. We will cover some of this in a separate post in the future. 

BIM 360 Glue API Samples 

 
 

The Windows Desktop Client (Test Harness) and ASP.NET Web Applications are Visual Studio 2010 Projects written in C#. The original versions can be downloaded from the SDK page, but please note the SDK page may not contain updated samples.

What do I need to do to get access to Glue API?

If you are already a Glue Customer, then there is nothing else you need to do. You can simply request an API key and secret to be issued through your contract. For Developers, you can also request developer access through Autodesk Developer Networks DevHelp online. If you are looking for technical resources to develop an integration for you organization, Autodesk Consulting would be a good partner to engage with. 

Looking forward to hearing from you about the exciting apps or integrations you are bulding using BIM 360 Glue APIs. I will be back with more news and sample applications.

Happy Glue'ing!

Comments