REST Api Docs - Document
Currently, a document is a diagram, and diagrams are what Gliffy is all about. A Document can be created, viewed, or edited.
Method Summary
- List Documents in an Account
- Get meta-data for a single Document
- Create a new Document
- Get a Document as XML, SVG, or as an image
- Update Document meta-data
- Update Document content
- Delete a Document
- Put a Document in a different Folder
List Documents in an Account
This is a basic document query service that lists all documents in the account.
Request URL
| HTTP METHOD | URL |
|---|---|
| GET or POST | $API_ROOT/accounts/$YOUR_ACCOUNT_ID/documents.xml?action=get |
Parameters
| PARAMETER | REQUIRED | POSSIBLE VALUES | DESCRIPTION |
|---|---|---|---|
| get | Yes | get | |
| public | no | true | false | If "true", only documents that are public are returned in the given account. If "false", only non-public documents in the account are returned. If omitted, all documents are returned |
Example Response containing <documents>, and a single <document>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true">
<documents>
<document num-versions="2" id="1000003">
<name>Booze DB</name>
<mod-date>1215538283000</mod-date>
<create-date>1215538283000</create-date>
<published-date>1215538283000</published-date>
<owner id="208">
<username>moe</username>
<email>moe@BurnsODyne.apiuser.gliffy.com</email>
</owner>
</document>
<document is-public="true" 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>
</documents>
</response>
Get meta-data for a single Document
You may wish to get meta-data about one document in particular and not have to sort through the entire list.
Request URL
| HTTP METHOD | URL |
|---|---|
| GET or POST | $API_ROOT/accounts/$YOUR_ACCOUNT_ID/documents/$DOCUMENT_ID/meta-data.xml?action=get |
Parameters
| PARAMETER | REQUIRED | POSSIBLE VALUES | DESCRIPTION |
|---|---|---|---|
| get | Yes | get | |
| showRevisions | no | true | false | If true, show a nested list of the document revisions or versions, with meta-data for each. |
Example Response containing <documents>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true">
<documents>
<document is-public="true" num-versions="2" id="1000003">
<name>Booze DB</name>
<mod-date>1215538283000</mod-date>
<create-date>1215538283000</create-date>
<published-date>1215538283000</published-date>
<owner id="208">
<username>moe</username>
<email>moe@BurnsODyne.apiuser.gliffy.com</email>
</owner>
<versions>
<version id="1000002">
<num>1</num>
<create-date>1215538283000</create-date>
<owner id="208">
<username>moe</username>
<email>moe@BurnsODyne.apiuser.gliffy.com</email>
</owner>
</version>
<version id="1000026">
<num>2</num>
<create-date>121559943322</create-date>
<owner id="208">
<username>moe</username>
<email>moe@BurnsODyne.apiuser.gliffy.com</email>
</owner>
</version>
</versions>
</document>
</documents>
</response>
Create a new Document
In Gliffy, you must explicitly create a document before editing it. See getting the Gliffy Editor Launch Link to enable your users to edit a document. Diagrams are private by default in Premium accounts, and public by default in Basic accounts. Before creating a diagram, it's a good idea to check the Account status so that you know if the Diagram will be public or private. Your users will want to know!
Request URL
| HTTP METHOD | URL |
|---|---|
| POST | $API_ROOT/accounts/$YOUR_ACCOUNT_ID/documents.xml?action=create&documentName=$NEW_NAME&documentType=diagram |
Parameters
| PARAMETER | REQUIRED | POSSIBLE VALUES | DESCRIPTION |
|---|---|---|---|
| action | yes | create | |
| documentName | yes | Any string | The name of the document |
| documentType | yes | diagram | The type of the document |
| templateDiagramId | no | any diagram id | If document is a diagram, the id of a diagram that should serve as the initial version of the new diagram (this is how you can achieve "copying" of diagrams). |
| folderPath | no | The path to a folder in your account that the logged-in user has access to | initial folder the document will live in. The requesting user must have access to this folder (and it must exist, as well). If this is omitted, it will go in your account's default folder (which is ROOT) |
Example Response containing <documents>, and a single <document> that was created
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true">
<documents>
<document num-versions="2" id="1000003">
<name>Booze DB</name>
<mod-date>1215538283000</mod-date>
<create-date>1215538283000</create-date>
<published-date>1215538283000</published-date>
<owner id="208">
<username>moe</username>
<email>moe@BurnsODyne.apiuser.gliffy.com</email>
</owner>
</document>
</documents>
</response>
Get a diagram Document as XML, SVG, or as an image
This can be used in several ways. The simplest is to put this inside an HTML <img> tag to render the diagram inline with some text. You can also use this to download the image bytes for client-side caching, or to get an SVG version of the diagram, for import into Visio. As such, this call supports conditional GET, meaning you can cache either the last modification time or the entity tag and use them in your request to save network bandwidth
Request URL
| HTTP METHOD | URL |
|---|---|
| GET or POST | $API_ROOT/accounts/$YOUR_ACCOUNT_ID/documents/$DOCUMENT_ID.$EXTENSION?action=get |
Parameters
| PARAMETER | REQUIRED | POSSIBLE VALUES | DESCRIPTION |
|---|---|---|---|
| action | Yes | get | |
| size | no |
|
for rastered representation types (JPEG or PNG), this controls the size of the returned image. Ignored for SVG and XML. |
| version | no | a number | if present, represents the version of the diagram to retrieve. The first version is version '1'. If omitted, the current version is retrieved. |
Extension Types for File Formats
This table below shows the possible values for $EXTENSION
| FORMAT | MIME TYPE VALUE | EXTENSION | DESCRIPTION | DEFAULT |
|---|---|---|---|---|
| JPEG | image/jpeg | .jpg | Diagram as JPEG image | no |
| PNG | image/png | .png | Diagram as a PNG image | no |
| SVG | image/svgxml | .svg | Vector format that is suitable for importing into Visio, or high-resolution printing | no |
| GliffyXML | text/xml | .xml | This is the Gliffy native XML format. This is the Gliffy native XML format but is subject to change and should not be relied upon. | yes |
Update Document meta-data
You can rename a document at any time, and you can also make it public (or make it private to your account).
Request URL
| HTTP METHOD | URL |
|---|---|
| POST | $API_ROOT/accounts/$YOUR_ACCOUNT_ID/documents/$DOCUMENT_ID/meta-data.xml?action=update |
Parameters
| PARAMETER | REQUIRED | POSSIBLE VALUES | DESCRIPTION |
|---|---|---|---|
| action | Yes | update | |
| documentName | no | any string | the new name of the document. If omitted, the name will not be changed. |
| public | no | true | false | If "true", this document will be made public; anyone on the internet can view it or use it as a template (you still retain rights to modify it, however). If "false", this document will be made "private" (it will still be accessible to anyone in your account with access to the folder in which the document resides). If omitted, the "publicness" of the document will not be changed |
Example of successful <response>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response xmlns="http://www.gliffy.com" success="true" />
Update Document content
Update the content of a document. This will create a new revision of the document being updated. WARNING!
We do not recommend that you programatically modify the content of the document because validation of the content is not currently conducted AND we fully expect the current document format to change.
Request URL
| HTTP METHOD | URL |
|---|---|
| POST | $API_ROOT/accounts/$YOUR_ACCOUNT_ID/documents/$DOCUMENT_ID.xml?action=update&content=$CONTENT_AS_XML |
Parameters
| PARAMETER | REQUIRED | POSSIBLE VALUES | DESCRIPTION |
|---|---|---|---|
| action | yes | update | |
| content | yes | XML of the new document content |
Example of successful <response>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true">
<documents>
<document num-versions="3" id="1000003">
<name>Booze DB</name>
<mod-date>1215538283000</mod-date>
<create-date>1215538283000</create-date>
<published-date>1215538283000</published-date>
<owner id="208">
<username>moe</username>
<email>moe@BurnsODyne.apiuser.gliffy.com</email>
</owner>
</document>
</documents>
</response>
Delete a Document
WARNING:This cannot be undone
Request URL
| HTTP METHOD | URL |
|---|---|
| DELETE or POST | $API_ROOT/accounts/$YOUR_ACCOUNT_ID/documents/$DOCUMENT_ID.xml?action=delete |
Parameters
| PARAMETER | REQUIRED | POSSIBLE VALUES | DESCRIPTION |
|---|---|---|---|
| action | yes | delete |
Example of successful <response> after a deletion
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response xmlns="http://www.gliffy.com" success="true" />
Put a Document in a different Folder
A document can exist in one and only one folder
Request URL
| HTTP METHOD | URL |
|---|---|
| POST | $API_ROOT/accounts/$YOUR_ACCOUNT_ID/folders/$FOLDER_PATH/documents/$DOCUMENT_ID.xml?action=move |
Parameters
| PARAMETER | REQUIRED | POSSIBLE VALUES | DESCRIPTION |
|---|---|---|---|
| action | yes | move |
Example of successful <response> after a moving diagram
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response xmlns="http://www.gliffy.com" success="true" />