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.
While format-related chatter often drowns cyberspace, the pivotal role of APIs, the silent yet mighty gatekeepers of interoperability, frequently escapes the limelight. But fear not. This very post is about to flip the script!
Let’s embark on an exciting journey into the heart of APIs: understand their significance, discover their indispensability, and learn the art of crafting one ideally suited to improve the BIM workflows in the vibrant AEC industry.
What is an API?
An API is a set of rules and protocols that allows different software applications to communicate and share data. It serves as a bridge between different software systems, enabling them to interact without any user intervention.
Think of a restaurant. You (the user) give your order (a request) to a waiter (the API). The waiter takes this to the kitchen (the system), which prepares the food (the data).
The waiter then brings the food back to you (the response). Like the waiter, the API facilitates the interaction between you and the kitchen, making the data transfer process seamless and efficient.
To be precise, endpoints are the main element. These are URLs where APIs can be accessed. They correspond to server functions, e.g., “/users” could retrieve all users. Endpoints use HTTP methods like GET, POST, and DELETE for read, create, and delete operations.
A client sends a request to the URL to use an endpoint, sometimes with parameters. The server processes this and returns a response indicating success, failure, and potential data.
We could define an API as the middleman allowing your platform’s and third parties’ interoperability.
Why is Interoperability Important?
APIs are the cornerstone of interoperability in our digital world, allowing different systems and applications to communicate and share data leveraging digital transformation.
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, Twitter 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?
Developing an API for a product is an essential strategy that can be implemented at any stage of the product’s lifecycle. However, initiating API development from the onset of the product’s conceptualization can significantly enhance its benefits.
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 decide on the data format (like JSON or XML). After that, develop your API using a suitable programming language. Testing is essential to the API management process to ensure your API works as expected.
How to Document Your API
A well-documented API is as important as the API itself. It serves as a guide for other software developers to understand how to use your API. Include details like API endpoints, request/response examples, error codes, etc. Tools like Swagger or Postman can help generate and maintain your API documentation.
I always say that documentation of APIs should look like the example below of product instructions, where you have different sections structured:
- 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:
- Start a blog where you can post news and creative ways developers can use your API.
- Get a champion who loves your product and can communicate neutrally to the community. A great example of this is Jeremy Tamik on the Revit API.
- A forum is also essential, where anybody can ask questions, make requests and interact with other community members.
Practical Examples of APIs
Several APIs in the AEC industry can serve as excellent examples, below we put together a chart of the most used ones with a comparison:
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 abundant method that allow a developer to do practically everything, but the documentation and structure of the API itself are terrible when other APIs already have great-looking websites. Autodesk still provides this old-school desktop HTML file.
Autodesk Forge: A cloud-based set of APIs allows developers to create applications around Autodesk’s CAD and BIM software. With Forge, developers can integrate design data and automate design processes.
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 can be vulnerable to attacks. Ensure to implement measures like API keys, OAuth, or JWT for secure access.
- Versioning: As your API evolves, maintaining different versions can help avoid breaking changes for users using older versions.
- Testing: Regularly test your API to ensure it works as expected and provides accurate 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 models you can provide, the better,
Make Sure You Do Your API Workflow Automation Right
In conclusion, APIs offer tremendous benefits for your product. With the right approach, creating your API can streamline your BIM workflow process, automate tasks, and ultimately transform how your clients 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.
