API Best Practices

Consider these ideas as you build your integration with Gliffy. The following suggestions stem from our experience with building Gliffy integrations and from the feedback of our users.

• Typical Use Case / Flow
• Include an Add Diagram link
• Use a Gliffy Client Library
• Before creating diagrams over the API, check and see if the account is a Basic account
• Parameterize $API_ROOT for Gliffy Enterprise Support
• Create your own wrapper around the Gliffy Editor
• When a user logs out of your application, delete their OAuth token

Typical Use Case / Flow

The user experience for many applications might look something like the following (your particular integration may have a different flow, but this is a good guideline for content management systems interested in adding Gliffy functionality).

This application flow is based heavily on our Confluence Plugin. (Note that the Confluence Plugin doesn't currently use the Gliffy API) Try out the Gliffy Plugin for Confluence to see this flow in action.

Actors

• Gliffy API - The programming interface to Gliffy.
• Home Application - The application that is integrating with Gliffy thru the Gliffy API.
• User - The user who is using the Home Application
• Content - An HTML page or another target container that will hold a diagram. Typically this would be a wiki page or some other content in a web application.

Use Case

1. User indicates a desire to add a diagram to the Content. (See Add Diagram link below)
2. If a Gliffy User hasn't been provisioned in the Gliffy API for the user, the Home Application does this now.
3. The Home Application prompts the user to name the diagram.
4. The Home Application makes a request to the Gliffy API to create the diagram.
5. If the diagram was created successfully, the Home Application obtains a Gliffy Editor launch link from the Gliffy API
6. The User clicks on the launch link, edits, then saves the diagram. The user then returns to the home Application.
7. The Home Application writes an <img> tag in the Content containing a link to a JPEG or PNG of the Gliffy Diagram. The image link is obtained from the Gliffy API. Below the <img> there shall also be an 'Edit Diagram' link for the user.

Including an 'Add Gliffy Diagram' link

This suggestion is particularly useful for customers who are building content management systems that include Gliffy drawing capabilities. It is important to give your users a way to add Gliffy drawings in an intuitive way. Simply providing wiki-text isn't sufficient as users wont be able to easily find Gliffy. The best way we've found to solve this problem is to include an 'Add Gliffy Diagram' link in a prominent place on all pages that might include Gliffy Drawings. For wikis, you might want this where you have links to 'Add Page'.

MediaWiki Example

Confluence Plugin Example

Use a Gliffy Client Library.

We have developed several client libraries in different languages that address the complexity of OAuth and making calls to the REST API. Using a client library in your target language is a quick way to jumpstart your integration. Since the client libraries are open sourced under the Apache license, you are free to modify it to your needs.

Before creating diagrams using the API, check to see if the account is capable of creating private diagrams.

Gliffy only allows Premium account holders to create private diagrams. This is to encourage customers to upgrade their Basic accounts to Premium accounts.

Developers: It is important that you check the expiration date of your account prior to creating diagrams for users. If the account expiration date is in the past, all newly created diagrams will be public by default, and the account MAY NOT create private diagrams. If the expiration date has passed, the UI of the home application should notify the user that they may only create private diagrams if they upgrade to a Premium Gliffy account.

Parameterize $API_ROOT for Gliffy Enterprise Support

In the future, we may release an Enterprise version of Gliffy, which will enable you to have an isolated hosted environment (i.e. a private sandbox at yourcompany.gliffy.com) or even host Gliffy in your own environment. Gliffy Enterprise will support the Gliffy API just like Gliffy Online does. By creating a global variable in your code that references the $API_ROOT for all requests, your integration with Gliffy will be able to support Gliffy Enterprise with a single configuration change.

Create a wrapper around the Gliffy Editor

We suggest you wrap the Gliffy editor in your own html page for several reasons:

1. The OAuth security policy is such that a given URL can only be requested once. If you embed an OAuth signed URL directly in a page, the link can only be clicked once. Wrapping access to the editor will ensure that users that bookmark the Gliffy editor will always get a new and valid URL.
2. Your users may not know that the Gliffy editor is hosted from a different domain. This prevents any possible confusion for your users.

One easy way to accomplish this task is through an iFrame. Here's an example from the PHP client library that wraps the Gliffy editor:

      <html> 
            <head>
                <script type="text/javascript"> 
                    // After the user is done editing, we want to refresh the page that contains
                    // the diagram image so that the new image will show up
                    function returnToHomeApplication() { 
                        opener.location='index.php';
                    } 
                </script>
            </head>
            <body onbeforeunload="returnToHomeApplication();">
                <iframe src ="<?php echo $diagramEditorLink ?>" 
                           width="100%" 
                           height="100%" 
                           frameborder="0" 
                           marginheight="0" 
                           marginwidth="0">
                    <p>Your browser does not support iframes.</p>
                </iframe>
            </body>
      </html>
            

Delete a User's OAuth token when the Home Application logs out

Call the delete OAuth token request when your user logs out of your application. By deleting the OAuth token, any URL's created while the token was active will become invalid. This is a good idea as it will enhance the security of your integration.