API Overview

Getting Started with the Onshape REST API

This document describes APIs that will allow partners to interact with the Onshape system.

Please address questions to " api-support@onshape.com” for the fastest response.

NOTE The API is still under development. Many of the previous interfaces have been deprecated in favor of a more consistent API. All previously described interfaces should continue to work, but we reserve the right to remove support for them. Please update to use the new forms as described in the API Explorer.

Quick Start

  1. Use the API Explorer to see detailed documentation of the Onshape API. To use the API Explorer, subscribe in the Appstore at https://appstore.onshape.com, then add the Explorer to a document using the plus menu.
  2. Sample applications are available at https://github.com/onshape-public.
  3. Request access to the private forum for API and App Store development. Send an email to Lou Gallo (lgallo@onshape.com) requesting access to the partner forum. Include the email address you use for signing in to the Onshape production server (cad.onshape.com).

Create your own application and let us know how it goes. We look forward to your questions, comments, and a demo of what you build!

Onshape Appstore

Onshape will make applications available through the Onshape Appstore. The Appstore will be actively promoted to users, making it easy for users to find, purchase and use third party applications. Click https://appstore.onshape.com to view the Onshape Appstore.

The Lifecycle of an Application

Onshape expects that typical applications will follow this timeline:

Phase Description
Initial development Development will take place on Onshape’s Production stack - https://cad.onshape.com your application is initially only visible to yourself and members of teams that you create an specify in the developer portal.
Alpha testing When an application is ready for early named-user testing, Onshape may be able to provide user accounts for named test users, or you can add your own users to the Visibility team for your application.
Beta testing Once an application is ready for broader testing increase the number of users in the visiblity team. Additionally Onshape will work with you to complete the ready for release checklist.
Release Released applications will be promoted to public visibility on the Appstore (if appropriate) and become available for general use.

How Your Program Interacts with Onshape

The primary APIs provided by Onshape are REST interfaces that are accessed over HTTPS. The client can be a web server or a desktop application (including command line tools such as curl). Onshape does not support use of the APIs directly from a browser client due to cross-domain scripting concerns.

We anticipate that partner applications will interact with Onshape in three ways:

  1. File Exchange. Onshape provides extensive import and export translation capabilities to interact with applications that can read or write a variety of file formats.
  2. Live Link Integration. Desktop or server applications can use REST calls to read information from the Onshape servers, and store information back. These applications can gain “cloud value” by using Onshape data management capabilities for sharing, versioning and durability.
  3. In-Tab Integration. Web server applications can create a tightly integrated experience within Onshape by using a combination of REST and client-side APIs to build a seamless interaction by interacting with users inside an Onshape tab.

The following diagram illustrates basic desktop integration and cloud integration architecture. The REST, WebHook and Client POST messages are documented in this and additional API documents.

image

The Onshape Server Stack consists of a number of cooperating servers that provide the underlying support for the Onshape CAD experience. The Onshape servers are built with a variety of technologies, including Java and C++, database and message services, geometry and constraint management systems, and much more.

Partner cloud applications can be written in any web framework. Onshape provides a set of samples in Github. Onshape is also planning to provide a library that simplifies desktop application development.

The user interface code that runs in the Onshape browser client is written in Javascript.

You may notice that this diagram does not illustrate the Onshape mobile clients for iOS and Android devices; the development of 3rd-party mobile applications for Onshape is beyond the scope of this document.

Tools and Samples

Onshape provides a set of sample applications and tools to assist third party development. These samples demonstrate how to use the API from a variety of environments, including desktop Windows applications, node.js servers, Windows Azure servers and more.

The components of the sample applications written by Onshape are provided under the MIT License; applications may include other open source components as well.

For access to samples and tools, please visit https://github.com/onshape-public.

Tools

Onshape provides API Explorer - an application written using the Onshape API that offers REST documentation and a “try me” mode for experimenting with the REST interfaces. To use API Explorer, visit the Appstore, select the API Explorer app and click “Try for Free.” Then, add a new Application tab using the plus button:

image

Select “Add Application” to create a tab with the API Explorer.

Sample Applications

The easiest way to get started with the Onshape API is to look at the sample applications. Each sample application is provided as a Github repository. For access, go to https://github.com/onshape-public. More samples will be made available over time. The current samples are:

Name Description
STL Viewer View the mesh of a model in a new tab within an Onshape document. This application is written in node.js, and the Readme file describes how to deploy the viewer to Heroku for hosting. The viewer demonstrates OAuth authentication, navigating parts in an Onshape model, and retrieving a tessellated mesh of an Onshape part.
GLTF Viewer Visualize GLTF data translated from an Onshape model. This is a Node.JS application, and the README provides instructions for deploying to Heroku. The GLTF viewer demonstrates OAuth authentication, navigating Elements and Parts in an Onshape model, triggering a translation and obtaining the resulting data, and registering, listening for, and un-registering webhooks.
BOM Create a Bill of Materials for an Onshape assembly. This application is written in node.js and includes documentation on Heroku deployment. The bom application demonstrates OAuth authentication, assembly navigation, metadata retrieval and shaded view generation.
API Key A set of examples demonstrating the use of API Keys for Onshape authentication. This includes sample code for both Python and Node applications.
Windows A Visual C# application demonstrating the use of a wide variety of API calls using OAuth for authentication.

Architecture Overview

This document primarily describes partner applications that run as server applications and provide a UI that is displayed within an Onshape tab. The API described can also be called from applications that do not display inside an Onshape document. All access to the document must be made using a secure (HTTPS) connection.

It is important to understand how Onshape documents are structured in order to use the API.

Elements

All data in an Onshape document is stored in Elements (represented as tabs in the user interface). Onshape documents currently contain 5 kinds of elements.

  1. Part Studio (zero or more parts)
  2. Assembly (zero or more parts or assemblies)
  3. Blob (“Binary Large OBject”) This can be data provided by a partner, or by the end user. For example, the user can upload a PDF file, an image or a text file. Partner applications can store arbitrary data, but we recommend using the structured storage available in an Application element for better integration.
  4. Application. This is an element that presents an IFrame to the user. The user interface in the IFrame is managed by a server that can be provided by a third-party. Note that Onshape Drawings are a special case of an application element.
  5. FeatureStudio. This element contains the definition of Onshape Features which are defined in FeatureScript.

Workspaces, Versions and Microversions

A document is stored in Onshape as a collection of changes. Each individual change to the document creates a new “Document Microversion”. You can think of a “Workspace” as a branch of the document, similar to a branch in a source control system. As the document is edited, changes are applied to the active workspace, creating new Microversions. Periodically, the user may designate “Versions” of the document. A Version is a named snapshot of the entire document at some point in time (that is, at some Microversion).

You cannot change a Version of the document - all changes are applied to a Workspace (and create a new Microversion). Thus, while in general the GET methods of the API can read from a Version, Microversion or Workspace, the POST methods generally require a Workspace, and create a new Microversion when data is written to the document. (An exception is that it is possible to set metadata within a Version - this does not create a new microversion).

The following IDs are used by many of the APIs. Each ID (except for Geometry IDs such as Part, Face and Edge) is currently a 24-character string that is used internally by Onshape to uniquely identify the resource. The Geometry IDs are variable-length strings used to resolve to a specific geometric entity within a model.

User ID Identifies a single user.
Document ID The Document ID identifies a document. The logged-in user must be able to access the requested document for the API to succeed.
Workspace ID The Workspace ID identifies a workspace within the document. Workspaces are used to distinguish between different branches of the document.
Version ID The Version ID identifies a specific named version.
Microversion ID The Microversion ID identifies an internal revision of the document.
Element ID The Element ID identifies an element within the document.
Part ID
Face ID
Edge ID
The Part ID identifies a part within a part studio. The Part ID should generally not be stored for long-term use, as it is only expected to be valid during the course of a session. Note that a Part ID may reference a part that no longer exists if the model is changed, so it is best to specify a Version or Microversion to pick the context for the Part ID. Note that even with the Version or Microversion, internal changes to the Onshape system may result in the Part ID changing. Therefore, Onshape provides mechanisms for maintaining persistent references. See the associativity APIs for more information. Face and Edge IDs are used in similar ways, and will be documented in further detail.

Linked Documents

Although a document can contain a complex model tree involving many Part Studio and Assembly elements, it is often more efficient to split the content into multiple documents. Connections between the documents are always made from a document referring to a specific version of the target document. Once a version of a document is used as the target of a linked document, that document version will be preserved as long as any document references it, event in the containing document is deleted. In addition, any user that has access to the referring document will have limited read access to the target document, regardless of what permission grants are currently on the target document.

Configurations

Onshape Part Studios may be contructed to be configurable using Onshape Configurations. API calls that reference Part Studios (primarily within the Parts and Part Studios APIs) often accept a “configuration” parameter that identifies what specific configuraton of the Part Studios is being referenced. When not specified, the API implementation will typically use the configuration that is currently selected within the Part Studio, which means that an interactive ad-hoc API call will often behave as you expect, but might not behave consistently in an application, so be sure to specify the configuration parameter where applicable.

Authentication

Onshape uses the OAuth for authentication. The Onshape sample applications demonstrate how to use OAuth; additional documentation about the OAuth protocol is available on the web and in the OAuth item in the documentation list.

Using OAuth will be required for all application in the Onshape Appstore, and is strongly encouraged for general security and privacy in general. By using OAuth, customers can maintain control of their own passwords, and enable and disable applications according to the their preferences. For security and privacy, vendors should not capture and store customer passwords.

OAuth

Onshape uses standard OAuth2. See the RFC at https://tools.ietf.org/html/rfc6749 for a detailed description of OAuth. More details on Onshape’s OAuth implementation is available in the OAuth document.

Onshape provides the following OAuth endpoints:

https://oauth.onshape.com/oauth/token

https://oauth.onshape.com/oauth/authorize

The Oauth Header should be in the form:

‘Authorization: Bearer <_token_>’

The Onshape samples provide a working template demonstrating OAuth use. To build your own applications based on these samples, you will need an OAuth Client ID and OAuth Client Secret from Onshape.

You can generate an ID and Secret by using the Onshape Developer Portal at https://dev-portal.onshape.com.

You can also add your application to the Appstore using the Developer Portal. Note that by default, only Onshape, the Application Owner and members of the ‘visiblity team’ will be able to see the App in the Appstore.

Username and password

Authentication using username and password is now deprecated. This interface is not supported for applications in the Appstore.

UI Integration for Applications

Development and testing

Developers can create applications using the Developer Portal at https://dev-portal.onshape.com.

When your application is instantiated in a document, it will be called with a URL similar to the following:

https://_your-server.your-domain.com_?documentId=1bf13f86674e42e88da3ba72&workspaceId=b0526d577bb844bea463aea7&elementId=36c2f534a07941e1a26b4928&server=https%3A%2F%2Fcad.onshape.com&userId=53da35fbe4b0412c60b5e3b7&access=edit&debug=true

The query parameters passed from Onshape to your application are:

Parameter Description
documentId Current document ID
workspaceId Current workspace ID
elementId Current (application) element ID
server The address of the current Onshape server
userId Current user ID
access To be documented
debug To be documented

These query parameters provide the context you need to interact with the current document; you will need to authenticate to the Onshape server in order to use the REST APIs. The server parameter is informational, REST requests should always be sent to https://cad.onshape.com for API requests and https://oauth.onshape.com for OAuth related operations.

End user integration

When a user registers an application, there are several possible integration points to expose the application within the Onshape user experience. At this time, applications that provide a UI in an Onshape tab will be added to the menu attached to the plus button on the Onshape tab bar.

image

Use the Developer Portal to create an application and an Appstore entry. We are still considering how to best offer additional integration options, possibly including context menus for appropriate entities, application-specific toolbar buttons and more.

Applications for Mobile Clients

Onshape expects to enable applications tabs in iOS and Android environments, but details, including touch event handling in mobile environments, have not been finalized.

REST API Documentation

The available REST API endpoints are documented in the API Explorer. Documentation of deprecated forms of the API are provided for reference below.

IMPORTANT NOTE The documentation in the API Explorer reflects the supported interface. Some API calls may, for historical reasons, return additional undocumented fields. Unless the return fields are documented in the API Explorer, you should NOT use them, as they may be removed without warning. Your application should always ignore unexpected or undocumented return data. Onshape reserves the right to add, remove or change any undocumented fields.

API conventions

The Onshape API generally follows the following conventions:

  • Onshape generally supports only 3 methods: GET for read-only operations, POST for write operations, and DELETE for deletions. Onshape does not currently support other methods such as PUT.

  • Strings should be UTF-8 encoded.

  • Query parameters are used for optional parameters. All required parameters are included in the path.

  • For brevity, we use the following upper case letters in path definitions in this document:

  • D Document ID (24-characters)

  • W Workspace ID (24-characters)

  • V Version ID (24-characters)

  • M Microversion ID (24-characters)

  • E Element ID (24-characters)

  • The general form of a path is /resource/context/subresource. When present, the context identifies the document (D), the workspace, version or microversion (WVM), and the element (E). For example, to request the definition of an assembly within a workspace of the document: GET /api/assemblies/d/eb48129ebf9a499ea67d49fd/w/71534f2162b04565897e9769/e/4dd5d4d11fee45229d6e6ef8 or, more succinctly: GET /api/assemblies/d/D/w/W/e/E Note that the path elements “d”, “w”, “v”, “m” and “e” are abbreviated when used in the “context” section of the path.

  • Our intention is to provide Workspace, Version and Microversion forms for all appropriate GET operations. POST will always be to a Workspace, as Versions and Microversions are immutable. Not all forms of all interfaces are implemented at this time.

  • As of this writing, some API calls return information that is of use only for Onshape clients. You should generally only use the fields that are documented for external use. The internal data may be changed or removed without notice.

Current REST API list

API endpoints start with /api/, for example, /api/documents where the path segment following /api/ identifies the logical major resource with which they are associated. Our APIs are continuously evolving. Our policy with regard to maintaining API compatibility is that we may extend APIs to accept additional parameters and return additional fields in outputs without providing any advance notification. If we decide to modify an API in a way that would alter output in a meaningful way, we will either introduce a new API or define a new version of the existing API. API callers should take note of the documented Accept header for an API call and specify that in their application. When no version header is specified the behavior will behave according to the oldest supported version.

Please refer to the API Explorer for detailed information. The API Explorer describes the officially supported interfaces and documents all supported options and return values. You should only use documented fields. Internal data may be changed or removed without notice.

To obtain a complete list of API endpoints, open the API Explorer and click on the “Toggle All Endpoints” button to expand all available REST APIs. You can search this list using your browser’s search capability to locate specific interfaces.

Units parameters

The following strings are valid unit designators:

For length measures:

  • meter, meters, m
  • millimeter, millimeters, mm
  • centimeter, centimeters, cm
  • inch, inches, in
  • foot, feet, ft
  • yard, yards, yd

For angular measures:

  • degree, degrees, deg
  • radian, radians, rad
Last modified May 18, 2020