A Comprehensive Guide for API Workflow Automation in the AEC
A Comprehensive Guide for API Workflow Automation in the AEC
API Development and Integration Step by Step
Step right into the cutting-edge digital age world, where Application Programming Interfaces (APIs) aren’t just the unsung heroes but the vital backbone that breathes life into the realms of construction industry.
In a world often filled with discussions about formats, the crucial role of APIs, the silent yet powerful gatekeepers of interoperability, tends to be overlooked and often fades from the spotlight. But don’t worry! This very article is designed to change that narrative!
Join us as we embark on an exciting adventure into the very core of APIs: we will delve into their significance, uncover their essential nature, and master the skill of crafting one that is ideally tailored to enhance the Building Information Modeling (BIM) workflows within the dynamic Architecture, Engineering, and Construction industry (AEC).
What is an API?
An Application Programming Interface, commonly referred to as an API, is essentially a collection of predefined rules and protocols that facilitates communication and data sharing between different software applications. It acts as a crucial intermediary, or bridge, connecting various software systems, thereby enabling them to interact seamlessly with each other without requiring any direct user involvement or manual intervention.
Imagine you are in a restaurant. In this scenario, you, as the customer (the user), provide your order (a request) to a waiter (the API). The waiter then carries your request to the kitchen (the system), where the chefs diligently prepare your food (the data) according to the specifics of your order.
The waiter then returns with your food and presents it back to you (this is known as the response).
Much like the waiter in this scenario, the API serves as a vital facilitator for the interaction between you and the kitchen, ensuring that the entire data transfer process is not only seamless and efficient but also effortless from your perspective.
To be precise, endpoints represent the primary component of APIs. These are specific URLs at which the APIs can be accessed and interacted with by clients. Each endpoint corresponds to specific server functions, meaning that an endpoint like “/users” could be utilized to retrieve a complete list of all registered users within the system. Endpoints utilize various HTTP methods such as GET, POST, and DELETE, which are employed for performing read, create, and delete operations, respectively. A client initiates a request by sending it to a specific URL that corresponds to an endpoint, which may sometimes include additional parameters for more detailed interaction. The server then processes this request accordingly and returns a response, which indicates whether the operation was successful or if it failed, along with any relevant data that may be involved.
We could define an API as the middleman allowing your platform’s and third parties’ interoperability.
Why is Interoperability Important?
APIs serve as the fundamental building blocks of interoperability in today’s digital landscape, enabling various systems and applications to effectively communicate and share data, thereby harnessing the potential of digital transformation to its fullest extent.
They are the underlying mechanism that enables platforms like iOS, Android, and even Windows, with good examples like AutoCAD, Revit, Sketchup, etc., to interact with many third-party apps and services, thereby expanding their capabilities and user offerings.
For instance, X couldn’t provide feeds to display in other applications or let users post tweets from other apps without its API. APIs form the backbone of our interconnected digital ecosystem, allowing diverse applications to work harmoniously, creating a seamless, integrated user experience.
Without APIs, the seamless interoperability and rich user experiences we’ve come to expect across devices and platforms would not be possible.
In the context of the Construction Industry, interoperability is of the utmost importance due to the multi-disciplinary, collaborative nature of the sector.
It ensures seamless exchange and use of information across different software applications and platforms. This facilitates collaboration, enhances productivity, reduces information loss, and streamlines bim workflow process, thus boosting the project’s overall efficiency.
Everybody speaks about formats, whether we should use a proprietary one like Revit or open one like IFC or glTF, but there are limited discussions about APIs. Without them, no format exchange would ever work.
The Role of an API Workflow Automation
Think of APIs as secret superheroes. While many folks see them as an extra feature, they’re big game changers. APIs allow different computer programs to chat and share information effortlessly.
They also let other people use your API to build new things. This means your program could get even more features and, as a bonus, attract more users.
Before you know it, you might even have a whole community buzzing around your product. Yes, APIs act with real game-changing power.
In some cases, there are even products where the business is a specific API. Consider examples like Stripe, a platform that allows you to charge users for licenses or subscriptions.
Autodesk Forge, a group of APIs that charge you every time you use specific endpoints or even Mapbox, a group of APIs to display mapping information.
When to Create an API
We have already stated the benefits of having your API, so when is the best time once you decide to do it?
Creating an API for a product is a vital strategy that can be effectively implemented at virtually any phase of the product’s lifecycle. However, beginning the process of API development right from the early stages of the product’s conceptualization can markedly amplify its advantages and potential impact.
This practice is often encapsulated in the ‘API-first’ philosophy and advocates for the design and development of APIs to be prioritized before developing the actual product. This strategy allows developers to build products more efficiently and fosters interoperability, ensuring the product is designed to be extensible and adaptable in a rapidly evolving technological landscape.
How to Create Your API
The API development process involves several steps. First, define the purpose of your API. Next mastering API architecture, you need to consider best practices and principles like REST (Representational State Transfer).
You will also need to make a decision on the data format you wish to use, such as JSON or XML. Once you have chosen a format, you can proceed to develop your API utilizing an appropriate programming language that suit your project requirements. It is crucial to emphasize that thorough testing plays an essential role in the API management process, as it ensures that your API functions correctly and performs as expected under various conditions.
How to Document Your API
A well-documented API holds equal importance to the API itself and is crucial for its success. It acts as a comprehensive guide for other software developers, enabling them to easily understand and effectively utilize your API. Make sure to include vital details such as API endpoints, various request and response examples, relevant error codes, and other essential information. Powerful tools like Swagger or Postman can be incredibly helpful in generating and maintaining your API documentation efficiently.
I often say that the documentation of APIs should be organized and formatted similarly to product instructions, where you have distinct sections clearly structured for better readability and usability:
- Front Page: A nice-looking presentation of your API
- Index: The sections of the documentation
- How to use: A step by step how to use guide
- Warnings: Let the user know considerations or errors it might encounter and how to deal with them
- Parts: The different sections of the API
- Comments: Any additional information from the product creator of the API
Even when you have excellent documentation, there are always gonna be gaps in communication between your API and developers, so other actions are needed to complement it:
- Launch a blog platform where you can regularly share updates, insightful news, and innovative strategies for how developers can effectively utilize and maximize the potential of your API.
- Identify a champion who is genuinely passionate about your product and possesses the ability to communicate with the community in a balanced and impartial manner. An excellent illustration of such a champion is Jeremy Tamik, who is well-known in the Revit API community.
- A forum is also crucial and plays an essential role, providing a space where anyone can freely ask questions, submit requests, and engage in meaningful interactions with other members of the community.
Practical Examples of APIs
Numerous APIs within the Architecture, Engineering, and Construction (AEC) industry can be considered outstanding examples of effective application. In the following section, we have compiled a comprehensive chart that showcases the most commonly used APIs, providing a detailed comparison for your reference.
We have selected three APIs that illustrate different characteristics of the products in the AEC.
Revit’s API: an API that allows developers to interact with Revit and create custom plugins and add-ons. It enables the integration of external data, automation of repetitive tasks, and customization always within the Revit environment.
There are numerous methods available that enable a developer to accomplish virtually everything imaginable. However, the documentation and overall structure of the API itself often fall short, especially when compared to other APIs that boast impressive and user-friendly websites. In contrast, Autodesk continues to offer an outdated desktop HTML file for its documentation, which can be frustrating for people seeking a more modern and efficient user experience.
Autodesk Platform Services (Previously Forge) is a robust cloud-based collection of APIs that empowers developers to build innovative applications centered around Autodesk’s widely used CAD and BIM software platforms. By utilizing APS, developers have the capability to seamlessly integrate design data, manage workflows and complex tasks, and automate various design automation processes efficiently.
This API has excellent documentation and is structured in different APIs helps developers a lot, but from a technical point of view is not a great API. For example, if you want to upload a file to ACC, you have to traverse through 5 endpoints to finally be able to do it, when one as a developer might expect something more straightforward to use.
Mapbox API: Mapbox provides APIs for maps, geocoding, and navigation. It can be used in the AEC industry for integrating geospatial data, creating visualizations, and analyzing spatial information.
This is one of the best APIs used in the AEC world. It has a balanced combination of being easy to use from a technical standpoint, good documentation, and sound API structure, so it is easy to navigate and utilize.
Tips and Tricks for your API Development and Integration
- Security: APIs are often exposed to various types of attacks, making them potentially vulnerable. To safeguard against unauthorized access, it is essential to implement robust security measures such as API keys, OAuth protocols, or JSON Web Tokens (JWT) to ensure secure and reliable access.
- Versioning: As your API continues to evolve and grow, it becomes increasingly important to manage and maintain distinct versions. This practice can help prevent any breaking changes from affecting users who are still utilizing older versions of the API.
- Testing: It is essential to regularly conduct tests on your API to confirm that it operates as intended and consistently provides accurate and reliable data.
- Rate Limiting: Implement rate limiting to prevent misuse of your API and to ensure it can handle the load.
- KISS: Always keep it as simple as possible. Remember that it should be self-explanatory to any external developer wanting to use it.
- Examples: There is no limit to this. The more 3D models you can provide, the better.
Make Sure You Do Your API Workflow Automation Right
In conclusion, APIs provide significant advantages for your product in numerous ways. By adopting the right strategies, developing your API can enhance and optimize your BIM workflow process and automate various repetitive tasks, and ultimately bring about a significant transformation in how your clients conduct their work.
Remember that this is not just another feature but a crucial part of any program, and the sooner you start, the better. If we want to change how our industry works, the power to connect, interact and share data lies in the APIS.
Valentin Noves
I'm a versatile leader with broad exposure to projects and procedures and an in-depth understanding of technology services/product development. I have a tremendous passion for working in teams driven to provide remarkable software development services that disrupt the status quo. I am a creative problem solver who is equally comfortable rolling up my sleeves or leading teams with a make-it-happen attitude.
