Gliffy Online REST API: Folder

A folder is used for organizing documents and for allocating user permissions on documents.

If you plan to offer Gliffy to multiple customers through your Account, you should create nested folders to restrict user access.

Method Summary

List Folders in an Account

Request URL

HTTP METHOD URL
GET or POST $API_ROOT/accounts/$YOUR_ACCOUNT_ID/folders.xml?action=get

Parameters

PARAMETER REQUIRED POSSIBLE VALUES DESCRIPTION
action Yes get

Example Response containing <folders>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true">
    <folders>
        <folder is-default="true">
            <name>ROOT</name>
            <path>ROOT</path>
            <folder is-default="false">
                <name>Burns Top Secret</name>
                <path>ROOT/Burns Top Secret</path>
            </folder>
            <folder is-default="false">
                <name>Casino</name>
                <path>ROOT/Casino</path>
            </folder>
            <folder is-default="false">
                <name>Drunks Only</name>
                <path>ROOT/Drunks Only</path>
            </folder>
            <folder is-default="false">
                <name>Simpsons Family</name>
                <path>ROOT/Simpsons Family</path>
                <folder is-default="false">
                    <name>Bart Only</name>
                    <path>ROOT/Simpsons Family/Bart Only</path>
                </folder>
                <folder is-default="false">
                    <name>Maggie and Lisas Stuff</name>
                    <path>ROOT/Simpsons Family/Maggie and Lisas Stuff</path>
                </folder>
            </folder>
        </folder>
    </folders>
</response>

Create a Folder

Here, $FOLDER_PATH can be a series of folder names delimited with the forward slash ('/'), which imply a nesting/hierarchy of folders. Currently, there can be only one folder at the root, and it is called ROOT. So, any other folder path will be in ROOT, e.g. /accounts/1230043/folders/ROOT/software. Also note that the parent folders must all exist, and that the user executing this must have access to the folder.

Default Folder Permissions - Any user who exists in this Account at the time the Folder is created will get access to this new folder. Any User created after this Folder is created will not have access to this Folder.

Request URL

HTTP METHOD URL
POST $API_ROOT/accounts/$YOUR_ACCOUNT_ID/folders/$FOLDER_PATH.xml?action=create

Parameters

PARAMETER REQUIRED POSSIBLE VALUES DESCRIPTION
action Yes create

Example of successful <response>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true" />

Delete a Folder

Here, $FOLDER_PATH can be a series of folder names delimited with the forward slash ('/'), which imply a nesting/hierarchy of folders. You may not delete the ROOT folder, and you may not delete a folder that has any documents or other folders in it.

Request URL

HTTP METHOD URL
DELETE or POST $API_ROOT/accounts/$YOUR_ACCOUNT_ID/folders/$FOLDER_PATH.xml?action=delete

Parameters

PARAMETER REQUIRED POSSIBLE VALUES DESCRIPTION
action Yes delete

Example of successful <response>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true" />

List Documents in a Folder

Request URL

HTTP METHOD URL
GET or POST $API_ROOT/accounts/$YOUR_ACCOUNT_ID/folders/$FOLDER_PATH/documents.xml?action=get

Parameters

PARAMETER REQUIRED POSSIBLE VALUES DESCRIPTION
action Yes get

Example Response containing <documents>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true">
    <documents>
        <document num-versions="4" id="1000000">
            <name>Hounds Room</name>
            <mod-date>1215538283000</mod-date>
            <create-date>1215538283000</create-date>
            <published-date>1215538283000</published-date>
            <owner id="202">
                <username>monty</username>
                <email>monty@BurnsODyne.apiuser.gliffy.com</email>
            </owner>
        </document>
        <document is-public="true" num-versions="5" id="1000002">
            <name>SNPP Domain Model</name>
            <mod-date>1215538283000</mod-date>
            <create-date>1215538283000</create-date>
            <published-date>1215538283000</published-date>
            <owner id="203">
                <username>smithers</username>
                <email>smithers@BurnsODyne.apiuser.gliffy.com</email>
            </owner>
        </document>
        <document num-versions="2" id="1000001">
            <name>World Domination Flow</name>
            <mod-date>1215538283000</mod-date>
            <create-date>1215538283000</create-date>
            <published-date>1215538283000</published-date>
            <owner id="202">
                <username>monty</username>
                <email>monty@BurnsODyne.apiuser.gliffy.com</email>
            </owner>
        </document>
    </documents>
</response>

List Users with access to a Folder

Request URL

HTTP METHOD URL
GET or POST $API_ROOT/accounts/$YOUR_ACCOUNT_ID/folders/$FOLDER_PATH/users.xml?action=get

Parameters

PARAMETER REQUIRED POSSIBLE VALUES DESCRIPTION
action Yes get

Example Response containing <users>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true">
    <users>
        <user id="209">
            <username>barney</username>
            <email>barney@BurnsODyne.apiuser.gliffy.com</email>
        </user>
        <user id="205">
            <username>bart</username>
            <email>bart@BurnsODyne.apiuser.gliffy.com</email>
        </user>
        <user id="210">
            <username>discostu</username>
            <email>discostu@BurnsODyne.apiuser.gliffy.com</email>
        </user>
        <user id="204">
            <username>homer</username>
            <email>homer@BurnsODyne.apiuser.gliffy.com</email>
        </user>
    </users>
</response>

Grant a User access to a Folder

This will grant the user access to the given folder and all folders beneath it.

Request URL

HTTP METHOD URL
POST $API_ROOT/accounts/$YOUR_ACCOUNT_ID/folders/$FOLDER_PATH/users/$USERNAME.xml?action=update&read=true&write=true

Parameters

PARAMETER REQUIRED POSSIBLE VALUES DESCRIPTION
action Yes update
read Yes true Gives user read access.
write Yes true Gives user write access

Example of successful <response>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true" />

Revoke User access to a Folder

This will revoke the user's access to the given folder and all folders beneath it. Admin users cannot be removed from a folder.

Request URL

HTTP METHOD URL
POST $API_ROOT/accounts/$YOUR_ACCOUNT_ID/folders/$FOLDER_PATH/users/$USERNAME.xml?action=update&read=false&write=false

Parameters

PARAMETER REQUIRED POSSIBLE VALUES DESCRIPTION
action Yes update
read Yes false Gives user read access.
write Yes false Gives user write access

Example of successful <response>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true" />