FotoFlexer Home

FotoFlexer Open API

The FotoFlexer API provides a simple interface for external websites to harness the power of FotoFlexer. Utilizing minimal code, any website can add industry-leading online image editing capabilities. Possible uses include:

There is no registration process, no API keys, and no REST or SOAP. Setup is a breeze! FotoFlexer even provides sample code to get you up and running in no time.

To get started, read this guide, download the Integration Kit, and view the live API demo. Visit the Developer Center for more info.

By using FotoFlexer API, you agree to the API Terms of Use.


Table of Contents

  1. Overview
  2. Basic Setup
  3. Launching
  4. Photo Storage
  5. Extending The API & Foreign Language Support

Overview

API Flow Chart

FotoFlexer API uses standard Javascript to embed configuration parameters and instantiate a loader. All Javascript and application files are hosted by FotoFlexer.com. The integrating site instantiates FotoFlexer by specifying an image url, callback url, cancel url, and optional lang.

FotoFlexer launches in locale lang. Itloads the image specified at the image url for editing. After a user is finished editing, and clicks the "Save" button, FotoFlexer will store the image, and then make an http request for the callback url, passing the new edited image url as a parameter. If a user clicks "Cancel", FotoFlexer will then direct the browser to cancel url. This sequence is illustrated to the right.


Basic Setup

Setting up FotoFlexer API is straightforward, and consists of three steps:

  1. Configure Parameters
  2. Embed Javascript
  3. Configure Callback Script

1. Configure Parameters

There are four javascript variables that can be set. These are ff_image_url, ff_callback_url, ff_cancel_url and ff_lang.

Put together, these variables would look similar to this:

<script type="text/javascript">
     var ff_image_url = "http://www.foo.com/images/bar.jpg";
     var ff_callback_url = "http://www.foo.com/handler.php";
     var ff_cancel_url = "http://www.foo.com/Cancelhandler.gif";
     var ff_lang = "en-US";
</script>

2. Entry

FotoFlexer is initiated by redirecting (or loading into an iframe) the page: "http://fotoflexer.com/API/API_Loader_v1_01.php". This page must be passed the required configuration parameters.

FotoFlexer can be instantiated through a Javascript function call. An example function is:

function ff_activate()
{
window.location="http://fotoflexer.com/API/API_Loader_v1_01.php?ff_image_url="+ff_image_url+"&ff_callback_url="+ff_callback_url+"&
ff_cancel_url="+ff_cancel_url+"&ff_lang="+ff_lang;
}

This code, as well as the configuration code from step 1, may be placed anywhere on the page. For fastest page loading, FotoFlexer recommends placing this Javascript at the end of the HTML, right before the closing <body> tag. This will ensure that all page content is loaded before the browser attempts to initialize FotoFlexer.

3. Configure Callback Script

After a user has finished editing an image, FotoFlexer will save the image, store it on FotoFlexer's servers, and then redirect the user to the callback url with the new (edited) image url passed as a GET parameter. The script residing at the callback url must be able to parse the GET parameters, and then process the result. This may include fetching the image to store locally, saving the URL to a database, or updating the page via AJAX with the newly edited image.

Just about anything is possible with the callback url. Using PHP, the simplest implementation would be this:

<?php

// Parse parameters to get Image url
$image = $_GET['image'];
// Now copy the images to the local server.
copy($image,"/path/to/images/image.jpg");
?>

In a production environment, the callback script should authenticate the image source, and perform error checking. Examples of this are provided in the Integration Kit.


Launching

Once FotoFlexer API has been properly configured, it is instantiated through a Javascript function called ff_activate(). This function can easily be called through an onclick event anywhere on the page:

<a href="javascript:void(0);" onclick="ff_activate();">Edit Image</a>

ff_activate takes the values of the configuration variables, packages them into a URL with GET parameters, and then redirects the user.

Please download the Integration Kit for code examples and a working API implementation.


Photo Storage

FotoFlexer API will store all saved photos until 02:00 AM Pacific time. All saved photos are purged daily. You should not rely on the API to save your files. It is recommended that files are copied and stored immediatly upon callback.


Extending The API & Foreign Language Support

So far, this guide has illustrated the simplest type of interface between a website and FotoFlexer: a single image is edited, and then passed back to the site. Although this is sufficient for many applications, the API is highly extensible, and allows much more complex behavior. Extending the API requires knowledge of Javascript and server-side scripting, such as PHP.

In its simplest form, FotoFlexer API has two points of contact with the integrating site: entry and exit. The entry is made by a client calling a specific URL with certain parameters. The exit is made by FotoFlexer redirecting to the callback url with certain parameters. The actual packaging of the URL by the client, and the processing by the callback script, provide powerful avenues for customization and extension.

Foreign Language Support

FotoFlexer API calls are addressed to "http://fotoflexer.com/API/API_Loader_v1_01.php". To properly initialize FotoFlexer, several GET parameters must be sent along with the http request. These are:

A sample url would take the following form:

http://fotoflexer.com/API/API_Loader_v1_01.php? ff_image_url=http://www.foo.com/images/bar.jpg& ff_callback_url=http://www.foo.com/handler.php& ff_cancel_url=http://www.foo.com/cancelHandler.php& ff_lang=en-US

Passing Additional Callback Parameters

When a user clicks "Save" within FotoFlexer API, FotoFlexer will redirect the user to the callback url, appending the new image url as a GET parameter with the names "image". The url FotoFlexer redirects to would look something like this:

http://www.foo.com/handler.php?
image=http://fotos.fotoflexer.com/2007/08/31/abc123.jpg

The script residing at this url (in this case, "handler.php") would be responsible for parsing the GET parameters, and then performing any other actions.

The callback url need not be a simple file location. It may be a dynamic url, containing additional GET parameter. When FotoFlexer parses the callback url, it will recognize if additional GET parameter is present, and include those when it redirects. This allows the developer to pass session IDs, user IDs or other information to help maintain state while the user is editing. When passing multiple parameters, however, all &s must be escaped using %26 to ensure proper processing.

For example, the callback url could be:

http://www.foo.com/view_image.php?uid=1234%26aid=567%26baz=890

In this case, FotoFlexer would append parameters to the end, like so:

http://www.foo.com/view_image.php?uid=1234&image=http://fotos.fotoflexer.com/2007/08/31/abc123.jpg&uid=1234&aid=567&baz890

Extending the API allows for sophisticated behavior, including dynamically generated API instances and AJAX integration.


Get Started

Get started with FotoFlexer API today! Download the Integration Kit to get code examples in PHP, as well as see the various Javascript calls in action. The Integration Kit contains a fully functional API implementation. It's a great starting point for more advanced integration.