Update! Fusion Data Read APIs are out of beta and now in production with general availability. The technical details in this article are still accurate. See here for latest announcement https://forge.autodesk.com/blog/fusion-data-apis-are-now-generally-available
Fusion Data is the first full data model coming into the Forge data platform. You’ve heard us talking about the Forge data idea for the past few months and now it is a reality. Fusion Data API currently models data from Fusion 360, and includes the model assembly structure, thumbnail for each component, and the ability to subscribe to the Fusion 360 Milestone events. The term “Fusion” is referring to manufacturing data and will be extended to other technologies in the future. The idea of this data model is to be “the-source-of-truth” for the data. Any tools that author and write the data need to do so directly to the data model, and this makes it a central data repository.
What can you do with Fusion Data APIs today?
This is the first exposure of the Fusion Data model and currently we are providing read-only APIs for a limited data set. We have much more planned here, but wanted to get these APIs out to start getting your feedback.
This first installment includes:
- Navigating hub project folders, into the design file, and all the way down to the Fusion 360 component properties
- Accessing the Bill of Materials of the CAD design by traversing the hierarchy of parts within the model
- Using webhooks to notify a server-based application and trigger a downstream workflow whenever a milestone is created.
These first set of capabilities includes:
- Build standalone applications that generate an engineering Bill of Material
- Integrate with ERP systems (i.e. SAP) by leveraging the persistent IDs as anchors into Fusion Data
- Automate key workflows through events driven by the milestone creation operation
- Create a browsing experience that starts from the users hub and traverses down to granular design data
And we are excited to see what other use cases you have for these APIs!
GraphQL
As you start exploring the API, you will quickly see that we’ve chosen to expose this data through a more natural approach by using GraphQL. Why not REST APIs as we usually see? It has to do with underlying complexities in the data, and generic terminology of the platform. With GraphQL, it allows our internal architecture of the data and APIs to be generic and designed to support our needs, but
allows us to expose that data through GraphQL in a more intuitive and domain-specific way. Graph QL was designed to work with multi-relational, graph-like data, so it makes perfect sense. As the GraphQL site states: “Describe your data”, “Ask for what you want”, and “Get predictable results”. For example, with a REST API, you may get back hundreds or thousands of lines of data, just to select a few things you need out of it. With Graph QL queries, you can get back exactly what you want.
GraphQL Example
Let’s look at a simple example… After getting the three-legged token, and finding the component ids of the assembly structure, we can ask for specific component data. Here’s a GraphQL query:
query ComponentVersion($thisId: String!) {
componentVersion(componentVersionId: $thisId) {
id
partNumber
materialName
}
}
And when using the ID of the component we want data for, we get this in return:
{
"data": {
"componentVersion": {
"id": "<my id>",
"partNumber": "Blade Guard Base Pin",
"materialName": "Steel"
}
}
}Those “fields” shown as id, partNumber, and materialName are matching terms that are coming from Fusion 360. We can change the returned data by changing the query. For example, maybe we want to add the partDescription. Using that query:
query ComponentVersion($thisId: String!) {
componentVersion(componentVersionId: $thisId) {
id
partNumber
materialName
partDescription
}
}
which will now return:
{
"data": {
"componentVersion": {
"id": "<my id> ",
"partNumber": "Blade Guard Base Pin",
"materialName": "Steel",
"partDescription": "This is a standard position pin and can be ordered to size."
}
}
}By using GraphQL as the data access tool, it further supports our promise of more granular data. It means not only can you easily get the “source-of-truth” data, but you can easily filter down to exactly what you want, making it easier on the client side to use the data as needed.
Why and How to use GraphQL in code?
Like REST APIs being generic and supporting many development environments, GraphQL is also like this. For an “opinionated” reason why GraphQL is even better than REST API see this resource. GraphQL has already addressed a number of common languages. You can find details here: https://graphql.org/code/ and notice there is support for both server and client side.
Getting started with Fusion Data
Here are the resources we currently have. Please remember that we are releasing this in a beta mode and would love your feedback. Feel free to submit the survey multiple times if you have additional or new feedback.
• Fusion Data overview – This is a good overview to understand Fusion Data
• Fusion Data API documentation – There is a new Documentation tile in the docs set, too
• Fusion Data API Sample Workflows – These are referred to from the documentation, but also note there is a Fusion Data Explorer that can be useful to work with queries and understand the syntax and data that is available.
• Feedback Survey - Please provide your valuable input here. It's ok to fill it out multiple times as you explore the APIs
To create an app that can use Fusion Data you will need to add it in the “create app” portal. Make sure to select “Fusion Data” tile to be added to your application and the other services as shown below.
Feedback and Support
The Fusion Data public beta will run until late summer. We would really like to have your feedback during this public beta period – on everything from the value these APIs provide to you, to the developer experience and documentation usability. Please visit this survey link to provide feedback. Again, feel free to fill the survey multiple times if you come up with additional input. We’re excited to see how you might integrate the GraphQL APIs into your apps and workflows. Please do not hesitate to reach out and share your work! For API support, please use the regular Forge help, but make sure to say your question is in context of the Fusion Data API.
Forge Data Days
Also! We are having a traveling Forge Dev Days event coming to a city near you this summer. Check out the details here.