Quick Start

In this example, we will call an Onshape REST API endpoint to send a document name to our console. Please note that the sample shown on this page is only designed to be used as a quick start guide and does not represent a full Onshape application.

System Requirements

• You must be signed in to your Onshape account at https://cad.onshape.com (or https://companyName.onshape.com for Enterprise accounts).
• This example is coded in Python. The equivalent code is provided in other languages at the end of the example. To follow along with this tutorial, you can download and install Python here: https://www.python.org/downloads/.

Review the API Endpoint

1. Go to the API Explorer and scroll to Document.
2. Expand the GET /documents/{did} endpoint. Note that in the URL, the name of this API is getDocument.
3. Make a note of the URL structure and the parameters required to make this request. This will become the fixed URL part of our API call.
   
   For this endpoint, we only need to get the document ID from the document URL.
4. Scroll down and make a note of the Media Type that we’ll need to include in our header.
   

Review the Document

Navigate to this public document, and make a note of the document ID in the URL (e60c4803eaf2ac8be492c18e).

Create your API Keys

1. Go to https://dev-portal.onshape.com.
2. In the left pane, click API keys.
3. Click the Create new API key button.
4. Select the following permissions for your app:
   • Application can read your documents.
   • Application can write to your documents.
5. Click the Create API key button.
   
6. Copy both the access key and secret key from the pop-up window, save them somewhere, then click the Close button.
   IMPORTANT NOTE: You will not be able to find the secret key again, so save it somewhere safe!
   
7. The details for your application appear.
   
8. Open your terminal and run the following command, replacing ACCESS_KEY and SECRET_KEY with the access key and secret key you created above. Remember to include the colon (:) between the keys.
   • MacOS:

     printf ACCESS_KEY:SECRET_KEY | base64
     

   • Windows:

     powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"ACCESS_KEY:SECRET_KEY\"))"
     

9. You will receive a long, base-64-encoded string. You will need this string later, so keep it somewhere safe. We’ll refer to it as our CREDENTIALS.

Write Your Code

1. Create a new file called hello.py.
2. Start your file by importing the necessary libraries.
   

import requests 
import jsons

3. Next, define the URL for the API call:
   

# Assemble the URL for the API call 
api_url = "ASSEMBLED_URL"

4. Replace ASSEMBLED_URL with the fully formed API. This is where we’ll put together everything we’ve learned so far:
   1. The base URL:
      • https://cad.onshape.com/api
      • https://companyName.onshape.com/api for Enterprise accounts
   2. The fixed URL is specified in the getDocument API in Glassworks: /documents/{did}
   3. The document ID parameter from the public document URL to include in the fixed URL: {did}: e60c4803eaf2ac8be492c18e
   4. Together, this makes the URL for our API request: https://cad.onshape.com/api/documents/e60c4803eaf2ac8be492c18e
      
5. We don’t need to send any optional parameters with our request, so we can define them as an empty object:

# Optional query parameters can be assigned 
params = {}

6. Now, define your API keys:
   

# Use the encoded authorization string you created from your API Keys.
api_keys = ("CREDENTIALS")

7. Replace CREDENTIALS with the string you created in the last section.
8. Next, define your headers:
   

# Define the header for the request 
headers = {'Accept': 'MEDIA_TYPE',
          'Content-Type': 'application/json'}

9. Replace MEDIA_TYPE with the Media type we obtained from the API Explorer during the Review the API section above:
   

application/json;charset=UTF-8;qs=0.09

10. Put all the variables you just defined together into the request:
    

# Put everything together to make the API request 
response = requests.get(api_url, 
                       params=params, 
                       auth=api_keys, 
                       headers=headers)

11. And finally, print the name value from the response:
    

# Convert the response to formatted JSON and print the `name` property
print(json.dumps(response.json()["name"], indent=4))

12. Make sure your file matches the full example below:
    

import requests 
import jsons

# Assemble the URL for the API call 
api_url = "https://cad.onshape.com/api/documents/e60c4803eaf2ac8be492c18e"

# Optional query parameters can be assigned 
params = {}

# Use the encoded authorization string you created from your API Keys.
api_keys = ("CREDENTIALS")

# Define the header for the request 
headers = {'Accept': 'application/json;charset=UTF-8;qs=0.09',
           'Content-Type': 'application/json'}

# Putting everything together to make the API request 
response = requests.get(api_url, 
                        params=params, 
                        auth=api_keys, 
                        headers=headers)

# Convert the response to formatted JSON and print the `name` property
print(json.dumps(response.json()["name"], indent=4))

Run Your Code

1. Open your terminal and navigate into the folder where you saved your hello.py file: cd ~/<your-file-path>
2. Install the necessary modules:

python3 -m pip install requests
python3 -m pip install jsons

3. Run your code:
   python3 hello.py
4. Confirm that your console displays:
   "Onshape API Guide"

Other Language Examples

Remember to replace CREDENTIALS with your credentials.

cURL

Returns the entire response json. Scroll to the bottom to the see name field.

curl -X 'GET' \
https://cad.onshape.com/api/documents/e60c4803eaf2ac8be492c18e' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Authorization: Basic CREDENTIALS' 

JavaScript

import fetch from 'node-fetch'; 

async function getDocument(url='') {
    const response = await fetch(url, {
      method: 'GET', 
      headers: {
        'Content-Type': 'application/json', 
        Accept: 'application/json;charset=UTF-8;qs=0.09', 
        Authorization: `Basic ${btoa('CREDENTIALS')}`
      }
    });
    return response.json(); 
}

getDocument('https://cad.onshape.com/api/documents/e60c4803eaf2ac8be492c18e'
).then((data) => {
    console.log(data.name); 
});

C++

Returns the entire response json. Scroll to the bottom to the see name field.

#include <iostream>
#include <string>
#include <stdio.h>
using namespace std;

int main() {
    string url = "curl ";

    url += "-X 'GET' "; 
    url += "'https://cad.onshape.com/api/documents/e60c4803eaf2ac8be492c18e'"; 
    url += "-H 'accept: application/json;charset=UTF-8; qs=0.09' "; 
    url += "-H 'Authorization: Basic CREDENTIALS'"; 
    
    system(url.c_str());
    return 0; 
}

Python

import requests 
import jsons

# Assemble the URL for the API call 
api_url = "https://cad.onshape.com/api/documents/e60c4803eaf2ac8be492c18e"

# Optional query parameters can be assigned 
params = {}

# Use the encoded authorization string you created from your API Keys.
api_keys = ("CREDENTIALS")

# Define the header for the request 
headers = {'Accept': 'application/json;charset=UTF-8;qs=0.09',
           'Content-Type': 'application/json'}

# Putting everything together to make the API request 
response = requests.get(api_url, 
                        params=params, 
                        auth=api_keys, 
                        headers=headers)

# Convert the response to formatted JSON and print the `name` property
print(json.dumps(response.json()["name"], indent=4))