http://fotoflexer.com/api.php
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:
- Photo Repositories
- Dating Sites
- Social Networks
- Online Auctions
- Classifieds
- And more!
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.
- Overview
- Basic Setup
- Launching
- Photo Storage
- Extending The API & Foreign Language Support
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.
Setting up FotoFlexer API is straightforward, and consists of three steps:
- Configure Parameters
- Embed Javascript
- Configure Callback Script
There are four javascript variables that can be set. These are
ff_image_url,
ff_callback_url,
ff_cancel_url and
ff_lang.
- ff_image_url: This is the url of the image to be edited. It must be accessible via a web browser. For example, "http://www.foo.com/images/bar.jpg." If this is empty string, FotoFlexer will prompt the users to upload images from their local computers
- ff_callback_url: This is the url that will be called when the user is finished editing and clicks the "Save" button. FotoFlexer will redirect the user to whatever URL is specified here. In addition, a new GET parameters will be appended with the url of the edited image. For example, you could specify ff_callback_url as "http://www.foo.com/handler.php." FotoFlexer would then redirect to "http://www.foo.com/handler.php? image=http://fotos.fotoflexer.com/2007/08/31/abc123.jpg"
- ff_cancel_url: This is the url that will be called when the user clicks the "Cancel" button.
- ff_lang: This is the locale of the FotoFlexer application the user will see. Valid values are: en-US(default), da-DK, de-DE, es-ES, es-LA, fi-FI, fr-FR, it-IT, ja-JP, ko-KR, nb-NO, nl-BE, nl-NL, pl-PL, pt-BR, pt-PT, ru-RU, sv-SE, tu-TR, vi-VN, zh-CN, zh-TW.
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>
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.
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.
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.
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.
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.
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:
- ff_image_url: This is the url of the image to be edited. It must be accessible via a web browser. For example, "http://www.foo.com/images/bar.jpg."
- ff_callback_url: This is the url that will be called when the user is finished editing and clicks the "Save" button. FotoFlexer will redirect the user to whatever URL is specified here. In addition, a new GET parameters will be appended with the url of the edited image. For example, you could specify ff_callback_url as "http://www.foo.com/handler.php." FotoFlexer would then redirect to "http://www.foo.com/handler.php? image=http://fotos.fotoflexer.com/2007/08/31/abc123.jpg"
- ff_cancel_url: This is the url that will be called when the user clicks the "Cancel" button.
- ff_lang: This is the locale of the FotoFlexer application the user will see.
Valid values are: en-US(default), da-DK, de-DE, es-ES, es-LA, fi-FI, fr-FR, it-IT, ja-JP, ko-KR, nb-NO, nl-BE, nl-NL, pl-PL, pt-BR, pt-PT, ru-RU, sv-SE, tu-TR, vi-VN, zh-CN, zh-TW.
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
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 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.
