This document outlines the REST API for Gliffy. This is the web services layer upon which all integrations with Gliffy are performed. While you can certainly use the REST API directly, we have provided several client libraries for your specific programming language (or, if there isn't one, make one and make it available to others!). Currently the REST API returns responses in an XML format. In the future, other data formats may be supported (json, etc.).
When beginning a new Gliffy REST API session, the first step is to obtain a valid OAuth Token and OAuth Token Secret. A User is identified by a valid OAuth Token and OAuth Token Secret that has been obtained through a 2 legged or 3 legged authentication process. As a result, after the OAuth Token and Secret are obtained, all subsequent requests are to include the parameters oauth_consumer_key, oauth_token, oauth_signature_method, oauth_signature, oauth_timestamp, and oauth_nonce as described in section 7 of the OAuth Core 1.0 Spec.
Two legged authentication means that there are only two parties involved in the authentication process. In our case, the two parties are Gliffy and the Consumer. The first step is to make a Create a User's OAuth Token request by signing the request as described in the OAuth Consumer Request Specification. Please note that the OAuth Consumer Key provided in thiss request MUST be associated with an account that the User is a member of.
The main advantage of 2 legged authentication is that the user experience is seamless since no additional User interactions are required to initiate an API session. The disadvantage of this method is that the Consumer must have access to a valid set of OAuth Consumer credentials(key & secret) for the User's Account. A User should NEVER reveal their Account Consumer Key/Secret to a 3rd party, making this type of authentication only appropriate when the Account holder and Consumer are of the same entity.
Three legged authentication means that there are three parties involved in the authentication process. In our case, the three parties are Gliffy, the Consumer, and the User. Also known as the OAuth Dance, this is the authentication process described in section 6 of the OAuth Core 1.0 Spec. We expect to support 3 legged OAuth some day.... tell us if this is something you want.
URLs and documentation refer to variables via strings starting with a dollar sign ('$'). Here are the variables used, what they mean, and how to determine them:
|VARIABLE||MEANING||HOW TO DETERMINE||EXAMPLE VALUE|
|$GLIFFY_ROOT||The root of the Gliffy application||This is the URL endpoint for the application.||http://www.gliffy.com|
|$API_ROOT||The root of the Gliffy API||This is the URL endpoint for the API. All requests begin with this URL fragment and indicate the version of the API being called.||http://www.gliffy.com/api/1.0|
|$YOUR_ACCOUNT_ID||The unique numeric identifier for your account||This ID is assigned to you when you sign up for Gliffy. It is shown on the same page that displays your Consumer Key and Secret.||1130079|
|$USERNAME||The name of a user||The user logging in.||davetron5000|
|$FOLDER_PATH||The path to a folder||Depends on the folder, but this will usually start with ROOT, as all folders are under it||ROOT/C3|
|$DOCUMENT_ID||The numeric identifier of a document (diagram)||This is usually returned in an XML response from another call||3948474|
|$EXTENSION||A file format extension||Descripes the representation type desired for a request. This is typically XML (.xml), but can be other extensions when getting a Diagram as an image||.png|
Organizational entity, primarily for the purposes of billing and tracking usage.
Represents a single Gliffy document or diagram.
A named user who is a member of an account.
Organizes Documents and controls user permissions.
This sections describes how to construct a launch link that will take users to the Gliffy editor. This API call must be OAuth signed as described above. Please also refer to the section titled Create your own wrapper around the Gliffy Editor in the Best Practices document when building this part of your integration.
|GET or POST||$GLIFFY_ROOT/gliffy/?launchDiagramId=$DOC_ID&returnURL=$RETURN_URL&returnButtonText=$RETURN_TXT|
|launchDiagramId||Yes||A document id||The document id of the diagram the user is editing|
|returnURL||Yes||A URL||When the user clicks the 'Back to...' button in the Gliffy editor, this is where they are redirected to. This value must be URL encoded.|
|returnButtonText||Yes||Any text string||The text shown on the 'Back to...' button in the Gliffy editor. This value must be URL encoded.|
The following words may not be used as the name of a folder or a user:
Furthermore, foldernames and usernames must start with an alphanumeric character and account names for organizational accounts may not contain the "@" sign.
Some GET methods respond to a conditional get. Those that do include the "Last-Updated" header in their response, as well as an "ETag" header. It is recommended that you always perform a conditional get, if you have the ability to provide client-side caching. While not all GET requests to Gliffy support it, eventually they will.
Certain Gliffy resource will include an HTTP header for Last-Updated. If you store this with a copy of the data, you can avoid
re-fetching it if it hasn't changed. When you next make a request, include this date in the header
If-Modified-Since. If the data has not
changed, Gliffy will respond with an HTTP status of 304, indicating you may safely use your cached copy.
An alternate means is to use an "entity tag", which is essentially a hash of the data. Certain Gliffy resources will include an HTTP header for ETag. Save this value with the data. When you re-request the data, include the header If-None-Match and use the value of the ETag you stored in the cache. If the data Gliffy would serve you has not changed, it will have the same ETag, and Gliffy will return an HTTP status of 304, indiciating you may safely use your cached copy.
The REST API, by default, always returns an HTTP status of 200, with an XML response in the body. This makes developing and debugging much simpler and easier to use for a wide variety of clients.
You may want the API to operate in a way that more strictly adheres to HTTP/REST. To do this, simply set rest_strict as a request parameter. This will have the following effects:
The REST API always expects UTF-8 character encoding. No other character encoding is supported.