Cover image for Introduction to APIs
John Egan
John Egan

Posted on

Introduction to APIs

I thought that it would be valuable to share a ‘hello-world’ for APIs. Rather than trying to boil the ocean in one post, I wanted to provide some light reading which gives you a mental model of how to think about APIs, and that you maybe able to use this as a foundation to build upon.


Vendors such as Procore, Autodesk, Asite, Bentley and other cloud software providers offer APIs that expose an interface to their respective platforms to enable us developers to extend them with our own domain specific applications.

Please note the article focuses on Autodesk Forge APIs but concepts apply to the majority of vendor APIs.

An Overview of an API

Let's start by explaining what an API is. API is an acronym for Application Programming Interface and in short, it exposes some functionality belonging to a program so that it can be interacted with. Forge APIs are web APIs, which are simply an API that is accessible through internet specific protocols and is an enabler for developers to write custom applications to do stuff with said program via the internet. Let’s explain from a high level how this works using a restaurant as an analogy.

Tasty Burgers ...

We visit a restaurant, take a seat and order a burger from the kind waiting staff specifying that we would like it medium-rare with extra crispy bacon. The kitchen prepares our order according to what we have specified to the waiting staff and once complete, our burger is brought to our table to enjoy. In this case, the waiting staff is an interface for everything that happens behind the scenes and is responsible for delivering that value added item - Our tasty burger. The same principles apply when we use an API - The API documentation gives us the menu of things available to eat and any available options. Then, we send details of what we want to our API (i.e ), it does something, then returns data according to our specified input parameters.


This can enable us to write custom applications to interact with a program however the API allows. In context of an AEC project, this might include getting model information, updating project permissions, initialising projects using a set configuration or creating and deleting issues once resolved.

Autodesk Forge

As you browse the Autodesk Forge documentation, you will find high level categories of API such as “Model derivative API”. In this API you will find all of the functions to do with conversions of data formats that autodesk use to drive BIM360 and other platforms. If you think about when you upload a design file as a user of BIM360, you wait a while, then you can view it in their viewer. Thats because the file goes to this API to translate it into a format that the viewer can display in the BIM360 platform.



I hope this brief introduction to APIs will give you more confidence to take a look and imagine the possibilities to customise your cloud platform solutions.

If this has helped, please give me a thumbs up or if you have ideas to improve, please share!

Thanks for reading.

Discussion (3)

ralph_arcdox profile image
Ralph Montague

As I understand from your article above, there are API’s which simply (1) query data, or (2) manipulate/edit data, or (3) create new data – is that correct?

BIM360 Design Collaboration, uses a Central Revit file (or database) on Forge, which users link to using Revit Desktop application – it creates a “local file” on their PC, which synchronises with the “central file” on BIM360. So the file that is on BIM360, is the “real-time”, live/active reference file. Other disciplines, can reference this file into their own models (linked models). Once users save/uploads the Revit model to BIM360 DOCS, that model is a “copy at a point in time” – it’s no longer the “real-time” model. While it is useful to “query” the model in BIM360 DOCS, there is no-point in manipulating, or adding data to that model, as it is not the “live, real-time” model.

So my question is, whether the API’s can be used with the models on BIM360 Design Collaboration? ie Can edits, updates be made to the “central file” by the API’s (assuming user has adequate permissions to edit a file).

ralph_arcdox profile image
Ralph Montague

Probably related to the question above - in the BIM360 "Coordinate" (Glue) workflow, users "glue", or send their individual discipline models to the cloud, and the BIM360 Glue administrator them "merges" these models online to make the "federated model" for the purposes of clash detection, and also to connect to BIM360 Build App (previously Field). Again, these are copies of the models at a point in time, and not the "real-time" live models that are on BIM360 Design. Any data, captured on site through the "Build" App, are associated with these models on BIM360 Coordinate (Glue), until such time as users synchronise with "Glue". So, can API's interact with models on BIM360 Coordinate (Glue)?

brendanmcf profile image
Brendan McFarlane

Hi Ralph, you can access the "live" workshared models but it is a messy and risky process. Using Revit Design Automation you can open a cloud workshared Revit model but it opens it detached from central, not as part of a Revit worksharing session. If you make any changes you need to replace the original central model which has consequences (losing the history, risk of losing synced updates while offline etc...).