Folder Creation API for BIM 360 Docs

On By Mikako HaradaIn BIM 360, Docs, Forge

API to create a folder in BIM 360 Docs is finally available. Before you go back to your code and try it out yourself, however, I should point out a few things that you may want to be aware:

  • It uses commands (not POST-project-folders end point)
  • It supports in the user context only: i.e., 3-legged authentication and 2-legged with x-user-id specified. No full 2-legged is supported at this time.

Note that BIM 360 Team and other A360 based data management service uses POST-projects-folders endpoint to create a folder; the command version does not work for them. These may potentially add confusion if you are not aware up front. BIM 360 Docs team is aware of these gaps and will continue to work on to provide consistent, full 2-legged support at later time. For now, most importantly, we have a way to create folder!  Let’s take a look.

Folder Creation Command

Documentation:

URL: https://developer.api.autodesk.com/data/v1/projects/:project_id/commands

Method: POST

OAuth Scope: data:create

URL parameter:

  • project_id

Headers

  • Authorization: Bearer <token>
  • Content-Type: application/vnd.api+json
  • x-user-id: a user id in case of 2-legged authentication (optional).

You can obtain user id, using GET-users-@me endpoint.

Body looks like below:


{
    "data": {
        "type": "commands",
        "attributes": {
            "extension": {
                "type": "commands:autodesk.core:CreateFolder",
                "version": "1.0.0"
            }
        },
        "relationships": {
            "resources": {
                "data": [
                    { "type": "folders", "id": "1" }
                ]
            }
        }
    },
    "included": [{
        "type": "folders",
        "id": "1",
        "attributes": {
            "name": "API Folder1",
            "extension": {
                "type": "folders:autodesk.bim360:Folder",
                "version": "1.0.0"
            }
        },
        "relationships": {
            "parent": {
                "data": { 
                             "type": "folders", 
                             "id": "urn:adsk.wipprod:fs.folder:co.cw-3qj5SQ8Wcuwy4VaThdg" 
                }
            }
        }
    }
    ]
}

where

  • urn:xxx (in blue) at the bottom is a parent folder id.
  • “API Folder1” (in green) under “included.attributes.name” is the name of the folder you are trying to add.
  • two “id“s (in orange) under “data.relationships.resources.data” and “included” have to match.

Below is another example. This time creating multiple folders. Notice that “data.relationships.resources.data” and “included” are both list. The multiple ids from the two lists pair or map by the values of  id:


{
    "data": {
        "type": "commands",
        "attributes": {
            "extension": {
                "type": "commands:autodesk.core:CreateFolder",
                "version": "1.0.0"
            }
        },
        "relationships": {
            "resources": {
                "data": [
                    { "type": "folders", "id": "1" }, 
                    { "type": "folders", "id": "2" }
                ]
            }
        }
    },
    "included": [{
        "type": "folders",
        "id": "1",
        "attributes": {
            "name": "API Folder1",
            "extension": {
                "type": "folders:autodesk.bim360:Folder",
                "version": "1.0"
            }
        },
        "relationships": {
            "parent": {
                "data": { 
                             "type": "folders", 
                             "id": "urn:adsk.wipprod:fs.folder:co.Bf6FgsnT_TRepl345z2CicQ" 
                }
            }
        }
    }, 
    {
        "type": "folders",
        "id": "2",
        "attributes": {
            "name": "API Folder2",
            "extension": {
                "type": "folders:autodesk.bim360:Folder",
                "version": "1.0"
            }
        },
        "relationships": {
            "parent": {
                "data": { 
                             "type": "folders", 
                             "id": "urn:adsk.wipprod:fs.folder:co.Bf6FsfT_TRegp36Bz2CicQ" 
                }
            }
        }
    }
    ]
}

What about Permissions?

A common question we have is about folder permissions. When you create a folder under a given folder, permission will be inherited from the parent folder. Currently, there is no API to control the folder permissions.

Note on 9/12/2017. Currently known issues and limitations:

  • 2-legged authentication + x-user-id is not accepted any longer due to the recent change. We are working on to allow this scenario. 3-legged authentication should continue to work (HS-3556).
  • Folders created through API displays URL encoded user name in the UI; e.g., a blank will be displayed as “%20”. (ALEX-14915).

The product team is looking into these issues.

Mikako

Leave a comment