Undocumented Private APIs
Onshape does a good job of documenting their public APIs and providing sample apps at https://github.com/onshape-public. However, it turns out that there is some functionality which may be needed for an application which wants to traverse the hierarchy of folders and documents which the application manages quite well. In the process of building an audit tool for the FTC Onshape library, we have discovered the following APIs.
GlobalTreeNodes API
At the top level, the system can find all of the treenodes by doing a GET
http://cad.onshape.com/api/globaltreenodes
This returns back a JSON structure with information about all the tree nodes which the other APIs take. Each of the entries in the items array has a number of attributes, most of which seem to be currently unused:
| Field | Typical value | Usage |
|---|---|---|
| subType | 0 | Magic ID |
| id | 0 | ID of element (same as subType) |
| name | Recently opened | Descriptive Name |
| treeHref | https://cad.onshape.com/api/globaltreenodes/magic/0 | URL to retrieve the data |
| isMutable | FALSE | Item can be changed |
| isContainer | TRUE | Item is a container |
| canMove | FALSE | Item can be moved |
| owner | null | Owner (currently unused) |
| description | null | Description (curently unused) |
| createdAt | null | Creation date (currently unused) |
| modifiedAt | null | Modified date (currently unused) |
| createdBy | null | Creation Userid (currently unused) |
| modifiedBy | null | Modified Userid (currently unused) |
| projectId | null | Project ID (currently unused) |
| isEnterpriseOwned | FALSE | Owned by an enterprise (currently unused) |
| resourceType | magic | Type of resource |
| href | null | Location of document (currently unused) |
Magic IDs
Using the GlobalTreeNodes api, we are told the various Magic ID values, and a little bit of experimentation allows us to identify the usage of these values:
| Magic ID | Title | Usage |
|---|---|---|
| 0 | Recently Opened | Most recently opened documents |
| 1 | My Onshape | Root folder and contents |
| 2 | Created by Me | Documents created by the logged in user |
| 3 | Public | All public documents (a very long list) |
| 4 | Trash | Trashcan for the logged in user |
| 5 | Tutorials & Samples | Desktop Tutorials |
| 6 | FeatureScript samples | FeatureScript samples (found when you select Other documents while adding a custom feature) |
| 7 | Community spotlight | Community spotlight (found when you select Other documents while adding a custom feature) |
| 8 | Tutorials | IOS Tutorials |
| 9 | Tutorials | Android Tutorials |
| 10 | Labels | Labels created by the user |
| 11 | Teams | Teams that the user is connected to |
| 12 | Shared with me | Documents shared with the user |
| 13 | Cloud Storage | Visual list of cloud accounts associated with the logged in user |
| 14 | Custom table samples | Custom table samples (found when you select Other documents while adding a custom table) |
GlobalTreeNodes Magic API
Based on this information, the API to return the list of elements in the section generally works like this:
http://cad.onshape.com/api/globaltreenodes/magic/0
As you can see, the magic number at the end indicates what pool of elements to return. Any other values other than the ones documented above result in a 404 – Not found response. T
Additionally, the API takes some additional URI parameters. (Of note here is that Onshape also passes them as a JSON body, but the API appears to ignore them)
| Field | Values | Default | Usage |
|---|---|---|---|
getPathToRoot | true/false | false | Return the description of the section |
limit | Integer | 50 | How many entries to return |
| offset | Integer | 0 | Which entry to start with |
sortColumn | name/modifiedby/modifiedAt | modifiedAt | Column of data to sort on |
sortOrder | asc/desc | asc | Which direction to sort |
The API is pretty resilient. If you pass a bad sortColumn value, it seems to pick a reasonable default. For fun, if you pass in an invalid limit value, you might get a nice German message of Ein unzulässiges Argument wurde angegeben. Überprüfen Sie Ihre Anfrage or the English equivalent An illegal argument was provided, please check your request.
| Field | Type | Usage |
|---|---|---|
| permissionSet | Boolean | Permissions (not currently used) |
| pathToRoot | Map | If requested, the description of the section |
| next | String | URL to retrieve the next set (if there are more to retrieve) |
| href | String | URL to retrieve this set of items. (Generally it should be the URL passed in to get the list) |
| items | Array of Maps | Ordered array of items matching the list |
GlobalTreeNodes Folder API
Once you have found a folder, to get the contents of the folder, the api is :
http://cad.onshape.com/api/globaltreenodes/folder/{fid}The {fid} is the folder id returned a 404 – Not found response. T
Additionally, the API takes some additional URI parameters. (Of note here is that Onshape also passes them as a JSON body, but the API appears to ignore them)
| Field | Values | Default | Usage |
|---|---|---|---|
getPathToRoot | true/false | false | Return the description of the section |
limit | Integer | 50 | How many entries to return |
| offset | Integer | 0 | Which entry to start with |
sortColumn | name/modifiedby/modifiedAt | modifiedAt | Column of data to sort on |
sortOrder | asc/desc | asc | Which direction to sort |
The API is pretty resilient. If you pass a bad sortColumn value, it seems to pick a reasonable default. For fun, if you pass in an invalid limit value, you might get a nice German message of Ein unzulässiges Argument wurde angegeben. Überprüfen Sie Ihre Anfrage or the English equivalent An illegal argument was provided, please check your request.
| Field | Type | Usage |
|---|---|---|
| permissionSet | Boolean | Permissions (not currently used) |
| pathToRoot | Map | If requested, the description of the section |
| next | String | URL to retrieve the next set (if there are more to retrieve) |
| href | String | URL to retrieve this set of items. (Generally it should be the URL passed in to get the list) |
| items | Array of Maps | Ordered array of items matching the list |
GlobalTreeNodes Items List
The items array returned from the globaltreenodes call is a map of values. If you look at the official documentation, it will start somewhere around https://github.com/onshape-public/go-client/blob/master/onshape/docs/BTGlobalTreeNodeInfo.md
| Category | Name | Type | Usage |
|---|---|---|---|
| Overall | BTGlobalTreeNodeInfo | ||
| jsonType | string | Indicates the type of object. It is one of document-summary,folder,magic,project,label,team-summary,cloudstorageaccount and the actual string indicates what additional fields may be available in the returned result. | |
| resourceType | string | A more human readable type of the object. Known values include Folder, Document | |
| name | string | Name of the object | |
| id | string | ID to access the object | |
| href | uri | API URI to access the object | |
| treeHref | string | API URI to get to the elements if this is a folder | |
| isContainer | boolean | Indicates that the object is a folder that can contain other objects | |
| isMutable | boolean | Can the object be changed | |
| isEnterpriseOwned | boolean | Object is owned by an enterprise | |
| canMove | boolean | Can the object be moved to a new location | |
| owner | BTOwnerInfo | Who owns the object | |
| createdBy | BTUserBasicSummaryInfo | Who created the object | |
| createdAt | date-time | When the object was created | |
| modifiedBy | BTUserBasicSummaryInfo | Who modified the object | |
| modifiedAt | date-time | When the object was last modified | |
| projectId | string | Project ID | |
| description | string | Some internal description. Seems to be blank | |
| viewRef | uri | ?????? | |
| Folder | BTFolderInfo | ||
| active | boolean | ||
| canUnshare | boolean | ||
| isOrphaned | boolean | ||
| parentID | string | ||
| permissionSet | Array of title/type permissions | ||
| trash | boolean | ||
| trashedAt | date-time | ||
| Magic | BTGlobalTreeMagicNodeInfo | ||
| subtype | integer | ||
| document-summary | BTDocumentSummaryInfo | ||
| jsonType | string | ||
| project | BTProjectInfo | ||
| trash | boolean | ||
| permissionScheme | BTRbacPermissionSchemeInfo | ||
| permissionSet | Array of title/type permissions | ||
| label | BTDocumentLabelInfo | ||
| team-summary | BTTeamSummaryInfo | ||
| cloudstorageaccount | BTCloudStorageAccountInfo | ||
GlobalTreeNodes Insertable Magic API
Sometimes the Application needs a lighter weight version of the list of items. An example is the Insert pasts and assemblies dialog which only needs pictures and descriptions. For this, the GET API is
http://cad.onshape.com/api/globaltreenodes/insertable/magic/0?&includeApplications=false...
Which returns less information, but it has more control over which sections are to be returned. These are passed on the URI:
| Field | Type | Usage |
|---|---|---|
| getPathToRoot | true/false | Return description of the section |
| includeApplications | true/false | Include Applications in the list |
| includeAssemblies | true/false | Include Assemblies in the list |
| includeBlobs | true/false | Include Blobs in the list |
| includeFSTables | true/false | Include FS Tables in the list |
| includeFeatureStudios | true/false | Include Feature Studios in the list |
| includeFeatures | true/false | Include Features in the list |
| includeFlattenedBodies | true/false | Include Flattened Bodies in the list |
| includePartStudios | true/false | Include Part Studios in the list |
| includeParts | true/false | Include Parts in the list |
| includeReferenceFeatures | true/false | Include Reference Features in the list |
| includeSketches | true/false | Include Sketches in the list |
| includeSurfaces | true/false | Include Surfaces in the list |
| includeWires | true/false | Include Wires in the list |
| limit | number | Total number of entries to return |
| offset | number | Starting offset for the list |
Searching
Another important API is the ability to search. This is done with an HTTP Post to
https://cad.onshape.com/api/documents/search
documentFilter: (magic number above)
foundIn: w/v/all
rawQuery:
when: all/latest
Global Storage Account
When you connect Onshape to your Google drive, Onshape needs to be able to determine what account to use in order to access it. The application uses
https://cad.onshape.com/api/cloudstorageaccount
in order to retrieve the list of accounts. This list is passed