Introduction to the Onshape REST API

Content

This page explains the basics of using the Onshape REST API. If you are brand new to using APIs, we suggest you spend some time learning the basics from these free resources:

Onshape uses REST APIs to communicate with clients and third-party systems. Onshape lives in your browser, which means you call REST APIs like you would any other web page. The API call returns information instead of a web page, and the response is formatted in JSON (JavaScript Object Notation).

You can use our REST APIs to access the Onshape engine and data in real time. We currently support three REST API requests (following the HTTP standards):

  • GET: Retrieve (read) information from the server (i.e., your Onshape documents). Any arguments included in the URL are sent to the server.
  • POST: Update (write) the server with new information. Required data is included in the request body.
  • DELETE: Delete information from the server.

A typical REST API call in Onshape includes five major components:

  • Method:
    • GET, POST, or DELETE
    • Every Onshape API endpoint is labeled with its method type.
  • URL:
    • Specifies the API endpoint and part of the document that the API is calling
    • Uses the following format: {base_url}/{fixed_url}.
      • {base_url}: Onshape URL (i.e., https://cad.onshape.com/api or https://companyName.onshape.com/api for Enterprise accounts).
      • {fixed_url}: the URL of the API endpoint (more about this later)
  • Query parameters:
    • Optional parameters for the API call
    • Described in the drop-down content of every endpoint in the API Explorer (you’ll learn about using our API Explorer in a later section).
  • Headers:
    • Defines the associated metadata, which is used by the server to process the request.
    • Usually contains Content-Type and Accept.
      • Content-Type:
        • Usually application/json
        • If the application downloads a file, Content-Type will be application/octet-stream
      • Accept: found under Media type in the API response section on in the API Explorer.
  • Payload body:
    • Only applicable for POST requests
    • Required for some POST requests; optional for others.
    • Body template is available in the API drop-down in the API Explorer.
    • Typically obtained and modified from the response of a related GET request (rather than manually)

Onshape API Request

Since Onshape is a web-based solution, it uses a URL to define what is loaded in the browser.

Example Onshape URL: https://cad.onshape.com/api/``documents/e60c4803eaf2ac8be492c18e/``w/d2558da712764516cc9fec62/``e/6bed6b43463f6a46a37b4a22

  • https://cad.onshape.com/api is the base URL of the document.
    • Every Enterprise account has a custom base URL: https://companyName.onshape.com/api
  • documents/ or d/ is followed by a 24-character document ID. The document ID uniquely identifies an Onshape document.
  • Next, w/ is followed by a 24-character workspace ID. The workspace ID uniquely identifies a workspace within the document. By default, a document is started with the Main workspace.
    • To refer to a specific document version, replace w/ with v/, followed by the 24-character version ID.
    • With every edit made in the document, a microversion of every document is automatically created with every edit. To refer to a specific microversion, replace w/ with m/, followed by the 24-character microversion ID.
    • Note: POST requests are always made to a workspace, since versions and microversions are immutable.
  • e/ is followed by a 24-character element ID. The element ID uniquely identifies an element (e.g., a tab that we see and access through the user interface).

In this documentation, we often refer to the URL template as: {base_URL}/{endpoint}/d/{did}/{wvm}/{wvmid}/e/{eid} or sometimes /{endpoint}/DWVME/ for short.

When your application is instantiated in a document, it is called with a URL like this:

https://_your-server.your-domain.com_?documentId=e60c4803eaf2ac8be492c18e&workspaceId=d2558da712764516cc9fec62&elementId=6bed6b43463f6a46a37b4a22&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, versionId, microversionId

Current workspace ID OR version ID OR microversion ID

elementId

Current (application) element ID

server

The address of the current Onshape server. The server parameter is informational; REST requests should always be sent to cad.onshape.com. Enterprise accounts should be sent to companyName.onshape.com.

userId

Current user ID, which can be found by calling /api/users/current and obtaining the user ID from the id field.

access

Set to edit if the document should open with edit capabilities.

Onshape API Response

The REST API in Onshape communicates data in JSON format. If you are new to working with JSON, we recommend the following resources:

The example below is the response from calling the getDocument API for this public document. A lot of information is returned, so we’ve truncated the middle of the response below, but if we look at the very end of the resulting JSON, we can see that the response has correctly returned Onshape API Guide as the document name.

 {
 "jsonType": "document",
 "documentThumbnailElementId": "",
 "isUpgradedToLatestVersion": true,
 "public": false,
 "permission": "FULL",
 "isOrphaned": false,
 "recentVersion": null,
 ...
 "isEnterpriseOwned": false,
 "resourceType": "document",
 "name": "Onshape API Guide",
 "id": "e60c4803eaf2ac8be492c18e",
 "href": "https://cad.onshape.com/api/v6/documents/e60c4803eaf2ac8be492c18e"
}

Versioning

All endpoint calls are versioned. The version string is inserted directly after the /api/ path component. For instance, https://cad.onshape.com/api/v6/documents/e60c4803eaf2ac8be492c18e indicates a version 6 request to the Onshape getDocument endpoint.

Calls within a version are compatible with one another; typically this means that a GET request can be fed back in as a POST at the same version. Versions are incremented whenever Onshape introduces a non-backwards-compatible change. Onshape users should always refer to the latest version in their calls. If no version is specified, the oldest version (v0) will be used.

API Conventions

The Onshape API generally uses 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). See the Onshape Architecture page for more information on Onshape’s basic API structure.
  • 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.

Unit Designators

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

What Now?

Continue on to our API Explorer page to learn about about navigating the Onshape APIs in our Glassworks API Explorer.

Link
https://onshape-public.github.io/docs/api-intro/
Summary
The article provides an introduction to using the Onshape REST API, explaining how to interact with Onshape using REST APIs, including GET, POST, and DELETE requests. It outlines the components of a typical REST API call in Onshape, such as method, URL, query parameters, headers, and payload body. The article also discusses Onshape API requests, including the structure of an Onshape URL and the parameters passed from Onshape to applications. It explains the JSON format used in Onshape API responses and the versioning of endpoint calls. Additionally, it covers API conventions, including supported methods, encoding, and path definitions. The article concludes by mentioning unit designators for length and angular measures and suggests exploring the API Explorer for further learning.