Many BIM 360 developers get a little confused about what APIs are available, and what is Forge in the context of BIM 360. This isn’t surprising as those products are APIs are rapidly evolving. I will try to clarify the status of API’s for BIM 360 as it stands today.
The fact that Forge is continuously evolving, in particular, Forge support for Docs is still under development, and is most likely contributing to the confusion. In addition, I see there are two factors that seem to make the API discussion for BIM 360 fuzzy:
- BIM 360 is a collection of different web services. Some are Forge while others are not.
- Forge is platform technology, which in turn is a collection of component technologies on top of which some of the BIM 360 web services are built.
Let’s talk about these two points to understand what Forge means and to clarify the role of Forge in the context of BIM 360 with a special focus on Docs.
BIM 360 Family Products
At the time of writing this article, we have six products with BIM 360 branding: Team, Glue, Layout, Docs, Field and Plan. The structure of BIM 360 web services family products looks like below:
(I’m assuming the reader of this post is familiar with the BIM 360 product. I’m not going to explain what each product does. If not, please refer to the BIM 360 product page.)
I used a similar image in the past in my presentations. A difference since then is the addition of BIM 360 Team. This is because of a branding change – BIM 360 Team used to be called A360 Team.
Forge vs. non-Forge
Autodesk Forge is a collection of web services that allows you to build your own applications and services. It is the platform technology that Autodesk uses to build its own services and products, and now Autodesk is opening it up to the developer community. As you can see in the image below, Team, Docs (*1) and HQ are parts of Forge, while the others are not. Glue/Layout and Field do have APIs, but they are legacy API and they are not a part of Forge. Plan and Building Ops do not have APIs at the moment.
*1) Currently in alpha. Accessible to Enterprise and NFR license holders only (more on this topic later).
What does it mean? Let’s take an example. One of the most frequently asked questions I get is this: “can we use Forge Viewer to display a model in Glue?” The answer is “no.” Due to historical reasons, Glue stores a model in its own storage and in its own format. It also uses its own viewer. You cannot use Forge Viewer to display a model. However, if you have a model in a storage managed by Forge Data Management, such as Team or Docs, you can display a model using Viewer. Right now, if you want to display a model in Glue using Forge Viewer, you will need to download a model from Glue and upload somewhere that supports the Forge Data Management API to access it.
Our view for the future is to have more data-centric architecture where data is stored at a common storage and shared across the BIM 360 family product services and beyond through the Forge API for a more seamlessly integrated and unified BIM 360. BIM 360 Docs is expected to play a role of holding data at the center. The image below depicts the architecture.
API for BIM 360 Docs – Big Picture
Let’s move on to the second point, i.e., Forge being platform technology and a collection of components on top of which some of BIM 360 are built.
API’s for BIM 360 Docs is a collection of Forge API’s. There is no single set of APIs that we name specifically as BIM 360 Docs API. This is different from a traditional desktop API, for example, Revit and AutoCAD API if you are familiar with them. As I mentioned earlier, Forge is a collection of web services that Autodesk is using internally to build its own products. BIM 360 Docs is a good example of such a product. The following is the list of Forge APIs that are used with Docs (image below):
- Authentication (OAuth)
- BIM 360 API (HQ or account level management)
- Data Management API
- Model Derivative API
- Viewer
- (Issues API) *2
Now, let’s look at each item.
Authentication or OAuth — this controls the user’s and application’s access to a specific account and to projects. When the user first accesses https://bim360docs.autodesk.com, for example, a login window appears, prompting the user for their Autodesk ID and password (image blow). OAuth API is used for this kind of user access. This is a common component that Autodesk products use.
BIM 360 API or HQ account level API — this gives full control over the HQ feature that you can access through bim360enterprise.autodesk.com. Note that this feature is specific to BIM 360. That’s why it is listed under BIM 360. This tends to be one area where people get confused. BIM 360 API only covers account level.
Data Management API — this gives access to projects, folders and items stored in Docs. This portion is probably the most analogous to the Docs’ purpose: stores data. Up to this point, we are dealing with a collection of files as data (image below).
Model Derivative API and Viewer — Once you get to a specific item that represents a single design data, you can use the Model Derivative API to access the model data. Information you can obtain using Model Derivative API could be geometry as well as meta data, such as properties attached to a certain element in Revit, for instance. You can use Viewer to display a model (image below).
Issues API (*) — The last item, Issues API, is to access Issues related data. I put asterisk (*) because this is still a bit of future item. We want to have Data Management portion completed first. Issues is something we want to have exposed through the Forge API as well as features that will be added on top of Docs. When new functionality is added, we would like to make it as generic as possible for scalability and expose it as Forge.
API for BIM 360 Team
Next, let’s look at APIs for BIM 360 Team. Team is based on Forge, too. Team uses the same API as Docs except that Team does not use HQ API and Issues API. HQ and Issues are specific to Docs (see the image below).
Non-Forge API
Lastly, I should add notes about Glue and Field. As mentioned earlier, Glue and Field are not a part of Forge, that is, they are not built using Autodesk’s common components. They do provide REST API and both have comprehensive coverage to access data. Those API’s do not provide viewing capability. We expect newer functionality be on Forge. As long as you are aware of this status, you are welcome to use it. You can find more information about Glue and Field API from the following links:
- Glue – https://fieldofviewblog.wordpress.com/glue/
- Field – https://fieldofviewblog.wordpress.com/field/
I hope this helps clarify what Forge is and what it is not in the context of BIM 360 API discussion, and how various Forge web services components fit together to work with BIM 360 Docs and Team.
Mikako
The Field of View 