Using the Onshape Client API with GO

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:

FieldTypical valueUsage
subType0Magic ID
id0ID of element (same as subType)
nameRecently openedDescriptive Name
treeHrefhttps://cad.onshape.com/api/globaltreenodes/magic/0URL to retrieve the data
isMutableFALSEItem can be changed
isContainerTRUEItem is a container
canMoveFALSEItem can be moved
ownernullOwner (currently unused)
descriptionnullDescription (curently unused)
createdAtnullCreation date (currently unused)
modifiedAtnullModified date (currently unused)
createdBynullCreation Userid (currently unused)
modifiedBynullModified Userid (currently unused)
projectIdnullProject ID (currently unused)
isEnterpriseOwnedFALSEOwned by an enterprise (currently unused)
resourceTypemagicType of resource
hrefnullLocation 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 IDTitleUsage
0Recently OpenedMost recently opened documents
1My OnshapeRoot folder and contents
2Created by MeDocuments created by the logged in user
3PublicAll public documents (a very long list)
4TrashTrashcan for the logged in user
5Tutorials & SamplesDesktop Tutorials
6FeatureScript samples FeatureScript samples (found when you select Other documents while adding a custom feature)
7Community spotlightCommunity spotlight (found when you select Other documents while adding a custom feature)
8TutorialsIOS Tutorials
9TutorialsAndroid Tutorials
10LabelsLabels created by the user 
11TeamsTeams that the user is connected to
12Shared with meDocuments shared with the user
13Cloud StorageVisual list of cloud accounts associated with the logged in user
14Custom table samplesCustom 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)

FieldValuesDefaultUsage

getPathToRoot

true/false

false

Return the description of the section

limit

Integer

50

How many entries to return
offsetInteger0Which 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.

The response JSON consists of several sections:
FieldTypeUsage
permissionSetBooleanPermissions (not currently used)
pathToRootMapIf requested, the description of the section
nextStringURL to retrieve the next set (if there are more to retrieve)
hrefStringURL to retrieve this set of items.  (Generally it should be the URL passed in to get the list)
itemsArray of MapsOrdered array of items matching the list
The use of the next field allows paging through the items without having the load the entire list (for example Public would be a bad one to try to get all in one shot).

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)

FieldValuesDefaultUsage

getPathToRoot

true/false

false

Return the description of the section

limit

Integer

50

How many entries to return
offsetInteger0Which 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.

The response JSON consists of several sections:
FieldTypeUsage
permissionSetBooleanPermissions (not currently used)
pathToRootMapIf requested, the description of the section
nextStringURL to retrieve the next set (if there are more to retrieve)
hrefStringURL to retrieve this set of items.  (Generally it should be the URL passed in to get the list)
itemsArray of MapsOrdered array of items matching the list
The use of the next field allows paging through the items without having the load the entire list (for example Public would be a bad one to try to get all in one shot).

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

CategoryNameTypeUsage
Overall BTGlobalTreeNodeInfo 
jsonTypestringIndicates 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.
resourceTypestringA more human readable type of the object.  Known values include Folder, Document
namestringName of the object
idstringID to access the object
hrefuriAPI URI to access the object
treeHrefstringAPI URI to get to the elements if this is a folder
isContainerbooleanIndicates that the object is a folder that can contain other objects
isMutablebooleanCan the object be changed
isEnterpriseOwnedbooleanObject is owned by an enterprise
canMovebooleanCan the object be moved to a new location
ownerBTOwnerInfoWho owns the object
createdByBTUserBasicSummaryInfoWho created the object
createdAtdate-timeWhen the object was created
modifiedByBTUserBasicSummaryInfoWho modified the object
modifiedAtdate-timeWhen the object was last modified
projectIdstringProject ID
descriptionstringSome internal description.  Seems to be blank
viewRefuri??????
Folder BTFolderInfo 
activeboolean 
canUnshareboolean 
isOrphanedboolean 
parentIDstring 
permissionSetArray of title/type permissions 
trashboolean 
trashedAtdate-time 
Magic BTGlobalTreeMagicNodeInfo
subtypeinteger 
document-summaryBTDocumentSummaryInfo 
jsonTypestring 
project BTProjectInfo 
trashboolean 
permissionSchemeBTRbacPermissionSchemeInfo
permissionSetArray 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:  

FieldType Usage
getPathToRoottrue/falseReturn description of the section
includeApplicationstrue/falseInclude Applications in the list
includeAssembliestrue/falseInclude Assemblies in the list
includeBlobstrue/falseInclude Blobs in the list
includeFSTablestrue/falseInclude FS Tables in the list
includeFeatureStudiostrue/falseInclude Feature Studios in the list
includeFeaturestrue/falseInclude Features in the list
includeFlattenedBodiestrue/falseInclude Flattened Bodies in the list
includePartStudiostrue/falseInclude Part Studios in the list
includePartstrue/falseInclude Parts in the list
includeReferenceFeaturestrue/falseInclude Reference Features in the list
includeSketchestrue/falseInclude Sketches in the list
includeSurfacestrue/falseInclude Surfaces in the list
includeWirestrue/falseInclude Wires in the list
limitnumberTotal number of entries to return
offsetnumberStarting 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