6 Things I Learned About the Onshape API

Out of the box, PTC’s Onshape is a professional-level, fully featured product development platform. Engineers, designers, researchers, educators, and students all over the world use it every day to turn their ideas into reality.

You could use Onshape for years, as I did, and never realize that Onshape’s cloud-native nature brings with it some unique and groundbreaking capabilities. One such capability is the API. If you’ve never heard of the API or have found it intimidating, keep reading to learn the top 6 things I learned when I finally decided to dive into the Onshape API.

1. What is an API?

I had been using Onshape for two or three years before the concept of an API, which stands for Application Programming Interface, started creeping into my consciousness. I’d occasionally see it mentioned in an Onshape Forums post or in a search result. But it seemed a little over my head, so I would just move on.

Then one day, I saw someone demonstrating a “digital twin” where the Onshape model of a robot arm controlled the robot’s “twin” in real life. I was so amazed by the demonstration that I had to know more. After a little research, here is what I learned.

Onshape was designed from the ground up to be cloud-native. That means that Onshape does not use part or assembly files to store your designs; all your modeling data lives in the cloud. When you use the Onshape interface, your actions are converted into messages that are sent from your web browser to the Onshape servers to be processed and stored.

Many of these messages are sent using Onshape’s API. It is how most modern cloud-based systems talk to each other. When you are online, whether you are fetching the latest news or posting a photo of your vacation, you are most likely using an API to send and receive data.

Specifically, Onshape’s API uses the common REST architecture. Many web applications use REST APIs for their simplicity, flexibility, and compatibility across different systems. When using Onshape, your web browser is making HTTP requests to what are called API endpoints. Each endpoint corresponds to a different task or resource, such as updating your model’s dimensions or material properties.

2. What can you use the API for?

The Onshape product interface is one of many ways to interact with your Onshape data. The Onshape API is open to all users. That means you can use API endpoints to fetch your model's thumbnail image, update a document name, or do almost any other action.

There are many reasons why a user might want to access Onshape data directly through the API rather than through the product interface.

A typical example is when a company uses systems other than Onshape to track product data. With only a few lines of code, the Onshape API can automate the transfer of data between systems to keep them in sync.

Another everyday use of the API is automating repetitive tasks. Exporting Onshape models requires a few clicks using the interface, but if you want to export a file for each of a model’s many possible configurations, using the API could save you hours.

Finally, Onshape’s App Store is full of third-party applications that extend Onshape’s native capabilities. These apps use the API to access Onshape data and process it to support simulation, PDM (Product Data Management), rendering, and other workflows.

3. What you can’t use the API for.

Once you discover the power of the Onshape API, a whole world of possibilities is now available. Use it to build your own digital twin, speed up analysis of your robot arm, or run a batch export of your design’s configurations. Just be aware that the API has limits, and by using the API, you are agreeing to some additional Terms of Use.

These limits are there simply to avoid abuse of the system, intentional or not. Be sure to avoid API loops that might generate thousands of calls. Also, using the API to scrape or data mine the Onshape Public Documents is prohibited.

4. You don’t need code to use the Onshape API.

This is what got me over the hump to finally start experimenting with the Onshape API. Onshape maintains an “API explorer” website called Glassworks that gives you access to all of the API endpoints without a single line of code. Using Glassworks gives you a real sense of what the API is, what endpoints exist, and how you might start using them for your own purposes.

To give Glassworks a try, begin by signing into Onshape. This authenticates your browser session and allows Glassworks to make requests to Onshape.

Next, launch Glassworks by going to cad.onshape.com/glassworks.

Scroll through the page, and you will see dozens of API endpoints organized by category.

Scroll down and click on the Document section to expand it. There are roughly 30 endpoints, each associated with a particular document action. Each endpoint is tagged with one of the three types of HTTP requests supported by the Onshape API: GET, POST, or DELETE.

GET requests retrieve data from the Onshape servers. POST requests send data back to the servers with the intent of updating information. DELETE requests permanently remove information from the servers.

Let’s make our first GET request. First, we need an Onshape document ID. In Onshape, open any document to which you have access and look at the URL for that document. Any Onshape document can be referenced using a unique 24-character ID, which you can find in the URL after the word “documents” and a slash. Copy that unique document ID.

In the Document section in Glassworks, find the /documents/{did} GET endpoint and expand it.

Paste your document ID into the “did” field and click the blue Execute button. Congratulations, you just made a GET request using the Onshape API! Scroll down to the responses section, and you should see a response code of 200 and a response body. That response body contains all kinds of information about your document, such as the name, when it was created, when it was modified, etc.

To explore the API further using Glassworks, check out the Introduction to the Onshape API course in the Onshape Learning Center.

5. You can make your own apps using the API.

Once you have explored the Onshape API using Glassworks and the Introduction to the Onshape API course in the Onshape Learning Center, you are ready to start building your own Onshape apps. A simple app might exist in the right panel of the Onshape interface and use the API to access document data.

Building your own app will require you to write some code, but the process for doing so is thoroughly documented in the Onshape Developer Portal. Your first app can be written in the language of your choice and can be run locally, eliminating the need to use a web host.

6. The API is secure.

It is important to note that data security is Onshape’s highest priority, and all Onshape API requests must be authenticated. If you were to try to make a request to the API but were not properly authenticated, you would receive a 403 error, which means you do not have permission to make that request. API keys securely manage all Onshape permissions and data access. Each Onshape user only has permission to view data for documents shared with them.