shelidonNovember 7, 2024Leave a Comment

Yesterday, we took a look at a brief introduction to the new AEC Data Model API, which targets data within files on your Autodesk Construction Cloud instead of drawing all of them and sifting through them later (which isn’t half bad when a system is paid per credit, let me tell you). Today we’ll try to get it started.

To start using the AEC Data Model API, you’ll need a few essentials in place, from getting an Autodesk Platform Services (APS) account to setting up your development environment and authenticating your API requests. Let’s dive into the necessary steps for a smooth setup, with a few tips along the way.

1. Registering for an Autodesk Platform Services Account

First things first: to access the AEC Data Model API, you’ll need an Autodesk Platform Services (APS) account. Signing up is pretty straightforward, and once you’re in, you can create an APS app that will generate your unique Client ID and Client Secret — the keys to unlocking API access. You’ll need to store these keys securely since they’re essential for every API call you’ll make.

A comprehensive step-by-step guide can be found on Autodesk’s own Before You Begin page, but here are the basics:

1. Sign Up on Autodesk: visit Autodesk’s APS portal and sign up for an account if you haven’t already;
2. Create an APS App: after logging in, go to the “Apps” section in the APS dashboard and click on “Create App”, name your app and set permissions based on your project needs;
3. Get API Credentials: once your app is created, Autodesk generates a Client ID and Client Secret. Store these safely (no, a post-it on the side of the screen is not “safe”): they’ll be needed for API authentication;
4. Enable the Required Scopes: choose the scopes (permissions) needed for your app based on your project requirements. For AEC Data Model API, select data and project-related scopes for adequate access.

2. Setting Up Authentication with OAuth

To interact with the AEC Data Model API, next you’ll need to authenticate using OAuth 2.0, a common standard for secure access to APIs. It may sound technical, but it’s essentially about confirming your identity and permission level to Autodesk’s servers.

Here’s how it works:

• You send a request to Autodesk’s authentication endpoint with your Client ID and Client Secret;
• If all goes well, Autodesk’s server sends you an access token, which is like a time-limited “pass” to make API calls.

You’ll use this token in the authorization header of your API requests, so hang onto it for the duration of your session (like holding a backstage pass while it’s valid). Once the token expires, security will kick you out and you’ll need to request a new one. For details, see the full guide on setting up OAuth.

3. Setting Up a Local Development Environment

With authentication out of the way, it’s time to set up a development environment where you can start making API calls and playing around with your data. Most developers use Node.js or Python to make HTTP requests to APIs, so pick your favourite programming language and get comfortable (if there’s any such thing).

Here’s a quick example to get your environment ready:

• Install your preferred language (Node.js or Python);
• Set up an IDE (like Visual Studio Code or PyCharm) to write and test your scripts;
• Install any necessary packages for making HTTP requests, such as axios for Node.js or requests for Python.

If all this sounds a bit intense, remember: it’s kind of like setting up your own “command centre” before a space mission. You’ll want everything in place to explore that universe of data. For detailed configuration and troubleshooting tips, see the Autodesk tutorial setup guide.

For instance, this is how the steps might look like if you’re picking Node.js and VSCode as your environment of choice:

• Install Node.js in the latest version from nodejs.org.
• Set Up Visual Studio Code (VS Code): VS Code is a versatile IDE for writing and testing your scripts. Download it from Visual Studio Code’s site, then install it on your machine;
• Install Git: Git is crucial for managing your code and accessing Autodesk sample repositories. Install it from Git’s official site;
• Download and Configure ngrok (Optional): Ngrok is a tunnelling tool useful for testing webhook integrations locally. It provides a secure URL to your local server, allowing APS to send callbacks to your local machine. Download ngrok from ngrok.com and configure it as per the instructions in the Autodesk setup guide;
• Clone the Sample Repository: For a head start, you can clone Autodesk’s tutorials repository from Autodesk’s GitHub page to access example code for common tasks.
• Install Required Packages: Open the project in VS Code and run npm install to install all dependencies. These will typically include packages for making HTTP requests, handling authentication, and parsing JSON data.

4. Getting Familiar with Hubs and Projects

Now that you’re ready to make API calls, it’s time to get familiar with hubs and projects in Autodesk’s world. Think of hubs as the parent containers that house projects, which in turn contain your folders and files.

Start with the getHubs endpoint to list all available hubs associated with your account. You can then use the getProjects endpoint to drill down into a specific hub and retrieve its projects. You’re officially down the rabbit hole — you’re pulling data from Autodesk’s cloud. For code samples, check out Autodesk’s tutorials on getting hubs and retrieving projects.

4.1. Get your Hub

For instance, on the Getting Hubs matter, the AEC Data Model API gives us the tools to access a top-level view of our project data across Autodesk’s cloud. As said, a hub acts as a container for projects, and each organization using Autodesk has its own. It’s the one you need to decide the geographic location for. To retrieve a list of hubs, you’ll need to make an authenticated API request to the getHubs endpoint, which will return details like hub ID, name, and type (account, project, etc.).

Here’s a step-by-step guide to making a getHubs request:

• Set Up Your Access Token: ensure your API request includes the OAuth 2.0 access token in the headers. Without this, Autodesk’s servers will politely decline your request.
• Make the API Call: send a GET request to the AEC Data Model API’s getHubs endpoint (https://developer.api.autodesk.com/project/v1/hubs). In Node.js, for example, my developer tells me this would look like:

const axios = require('axios');

async function getHubs() {
    const response = await axios.get('https://developer.api.autodesk.com/project/v1/hubs', {
        headers: {
            Authorization: `Bearer ${ACCESS_TOKEN}`,
        },
    });
    console.log(response.data);
}

• Review the Response: a successful call will return a JSON object listing each hub with details such as id, name, and type. The id is crucial because it’s the key to accessing specific projects and data within each hub.

This endpoint provides a valuable starting point to explore your organization’s project data. It’s like opening the front door to the Autodesk data ecosystem — from here, you can start exploring project structures, files, and deeper elements.

4.2. Getting Projects

Once you’ve accessed your hubs, the next step is to dig into each project within them. Each hub can contain multiple projects with their different size and scope as it’s typical for our industry. To retrieve a list of projects within a specific hub, use the getProjects endpoint by passing the hub ID.

Here’s how, to the best of my knowledge, this might look like:

• Set Up Your Request: send a GET request to https://developer.api.autodesk.com/project/v1/hubs/{hub_id}/projects, replacing {hub_id} with the actual hub ID from your previous call to getHubs.

const axios = require('axios');

async function getProjects(hubId) {
    try {
        const response = await axios.get(`https://developer.api.autodesk.com/project/v1/hubs/${hubId}/projects`, {
            headers: {
                Authorization: `Bearer ${ACCESS_TOKEN}`,
            },
        });
        console.log(response.data);
    } catch (error) {
        console.error('Error fetching projects:', error);
    }
}

• Explore the Response: the response will provide an array of projects within the hub, each with its unique project ID, name, and type. The project ID is crucial for navigating further into project data.

By listing projects within a hub, you’ll begin to see the full scope of activities and design data available for each specific project, setting the stage for deeper data exploration.

5. Navigating Project Elements

After accessing a project, the AEC Data Model API lets you dive deeper into its elements—the specific building blocks that make up your design. From walls and windows to complex HVAC systems, each element is categorized and organized hierarchically, as Revit users better know (Generic Model fans, I’m looking at you). The nav-elements endpoint is your gateway to this detailed project data, helping you visualize the structural layout and understand the relationships between different components. You can take a look here to see what Elements actually are in this context.

Autodesk’s tutorial on navigating elements is a great resource for getting started with this step, but let me try and guide you through it.

1. Use the nav-elements Endpoint: send a GET request to https://developer.api.autodesk.com/data/v1/projects/{project_id}/folders/{folder_id}/contents, substituting {project_id} and {folder_id} with the project and folder IDs relevant to your project.
2. Explore Hierarchical Structure: each response includes details on the element hierarchy, showing each component’s type, category, and its relationships to other elements. You might see structural groups like “Architecture” or “Electrical” that you can expand for more detailed views of individual elements within each category.
3. Filter for Specific Data: the response also supports filtering, letting you pull just the elements relevant to your task. This is particularly handy when focusing on specific categories, such as only structural or mechanical components, which helps simplify data handling. Remember that this is why we’re using GraphQL in the first place.

A request example might look like this:

const axios = require('axios');

async function getProjectElements(projectId, folderId) {
    try {
        const response = await axios.get(`https://developer.api.autodesk.com/data/v1/projects/${projectId}/folders/${folderId}/contents`, {
            headers: {
                Authorization: `Bearer ${ACCESS_TOKEN}`,
            },
        });
        console.log(response.data);
    } catch (error) {
        console.error('Error fetching project elements:', error);
    }
}

This API call gives you an organized view of all project elements, making it easy to find what you need and navigate between different layers of your model. For detailed instructions on navigating project elements, see Autodesk’s Navigating Project Elements tutorial.

6. Testing Your API Calls

As you begin making API requests, it’s essential to test each call to ensure you’re receiving the correct data. Autodesk suggests using tools like Postman or cURL for quick testing. These tools allow you to interact with the API endpoints directly, making it easy to debug issues or fine-tune your queries.

Testing with Postman can be as simple as pasting your endpoint URL, adding the necessary headers (like your access token), and clicking “Send.” This immediate feedback lets you see the JSON response and confirm that you’re on the right track before diving into code.

A Final Note: Embrace Experimentation

Setting up your environment may seem like a lot, but once everything’s in place, you’re free to explore the vast capabilities of the AEC Data Model API. Autodesk has designed the API to be flexible and accessible, so don’t be afraid to experiment with different requests, try out new endpoints, or dig into complex data. Whether you’re pulling data for reporting, setting up automation, or just exploring how things work, setting up a reliable environment will make every API call smoother. You’re just pushing and pulling the ends of all your projects through a tool you never tried before. What could go wrong?