Gliffy Online REST Api Overview

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.).

• Terms used in this document
• Authenticating requests with OAuth
• Variables used in the REST Documentation
• API Entity Operations
• Building a Gliffy Editor launch link
• Reserved Words
• Advanced Configurations
• Character Encoding

Terms used in this document

• Consumer - A website or application that uses OAuth to access Gliffy on behalf of the User. Also referred to as the Home Application.
• Account - An Account is used for several purposes:
  1. Represents a grouping of one or more Users on the Gliffy system.
  2. If the account is Premium, the Account represents the billing entity that will be charged User access to Gliffy.
  3. Identifies the entity that is initiating API requests.
• User - The end user of the Home Application. A User may be associated with one or more Accounts.
• Consumer Key / Consumer Secret - A set of OAuth credentials that are provided by Gliffy to the Consumer. These credentials are used used to authenticate a Gliffy Account and to request an OAuth token.
• Token / Token Secret - The key that uniquely identifies a user and account. This key is used to sign API requests to Gliffy. These key is obtained by the Consumer using a 2 Legged or 3 Legged OAuth workflow.

Authenticating requests with OAuth

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.

Getting an OAuth Token/Secret with Two legged authentication

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.

Getting an OAuth Token/Secret with Three legged authentication (available Summer 2009)

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.

Additional Details about Gliffy's implementation of OAuth

• POST requests may include parameters in the body (as what would happen with a form submission from a browser via a post), while DELETE and GET methods MUST include parameters as part of the query string
• ALL requests must specify the OAuth Signature method (oauth_signature_method). Currently, the Gliffy API ONLY supports signing using the HMAC-SHA1 signature method. Thus use "HMAC-SHA1", as the value of the parameter and make sure to sign your requests using the HMAC-SHA1 signature algorithm as defined in [RFC2104]
• Please review OAuth Core 1.0 Section 10 about HTTP Response codes and what to expect if there are OAuth specific problems.
• There is an excellent example here in the OAuth Consumer Request Draft of how to sign your request using OAuth and the HMAC-SHA1 signature method using ONLY the OAuth Consumer Key, which is the case when obtaining an OAuth Token in 2-legged authentication.

Variables used in the REST API Documentation

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

API Entity Operations

Building a Gliffy Editor launch link

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.

Launch Link URL

HTTP METHOD	URL
GET or POST	$GLIFFY_ROOT/gliffy/?launchDiagramId=$DOC_ID&returnURL=$RETURN_URL&returnButtonText=$RETURN_TXT

Parameters

PARAMETER	REQUIRED	POSSIBLE VALUES	DESCRIPTION
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.

Reserved Words

The following words may not be used as the name of a folder or a user:

• account/accounts
• admin/admins
• collaborator/collaborators
• document/documents
• token/tokens
• user/users
• image/images
• tag/tags

Furthermore, foldernames and usernames must start with an alphanumeric character and account names for organizational accounts may not contain the "@" sign.

Advanced Configrations

Other HTTP methods

• OPTIONS is not supported.
• HEAD will perform a GET but not include the response content. While you can use this for caching, Conditional GETs is a better means of doing this.

Conditional GETs

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.

Conditional GETs based on date

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.

Conditional GETs based on entity tag

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.

Strict REST Mode

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:

• Any response from the API that is not a "success" will return the HTTP status code appropriate to the error. You will not receive a <error>.
• Conditional GETs where the resource has not been changed will send an HTTP/304 and you will receive no <response>.
• Successful creation of resources (e.g. creating a new folder) will send an HTTP/201 and you will not receive a <response>.

Character Encoding

The REST API always expects UTF-8 character encoding. No other character encoding is supported.