Best Practice Makes Perfect

Collected wisdom from Picnik's developers

Encoding API Parameters

When you invoke the Picnik API using HTTP GET, you'll build up a URL with a list of parameters such as _import, _export, etc. Since you'll often be including one URL within another URL, you need to make sure that you've properly encoded all your arguments.

This is easy to do: just use an encoding function like PHP's rawurlencode to ensure that all invalid characters are properly converted. In practice, it's not uncommon to end up with double-encoded characters, which is perfectly valid. Here's why:

Let's say you want to edit a file stored on your server, the file's title is "Hello World", and you've got some code on your server that lets you access files by title. That file's URL on your server would then be something like:

http://www.example.com/?title=Hello%20World

If you want to send that file to Picnik, you might be tempted to pass a parameter like this:

_import=http://www.example.com/?title=Hello%20World

...but that won't work. You first need to encode the values of all parameters before adding them to your URL. So instead you want this:

_import=http%3A%2F%2Fwww.example.com%2F%3Ftitle%3DHello%2520World

Here's a good way to check: if http:// appears anywhere in your API URL other than the start of your Picnik API call, you're probably doing something wrong.

Assuming your initial URLs are all correct, here's some handy PHP code that will take care of all of this for you:

<?php
	$strPicnik = "http://www.picnik.com/service/?";
	$strPicnik .= "_apikey=YourApiKey";
	
	$aParams['import'] = "http://www.example.com/?title=Hello%20World";
	$aParams['title'] = "Hello World";
	$aParams['export'] = "http://www.example.com/export?title=Hello%20World";
	// etc...
	
	foreach ($aParams as $k => $v) {
		$strPicnik .= "&$k=" . rawurlencode($v);
	}
	
	echo $strPicnik;
?>

Handling HTTP POST Exports

We mentioned this briefly in our introduction to exporting, but it's worth repeating again: if you're handling HTTP POST exports from Picnik, you're going to get two hits to your website for each successful export. The first hit is a POST of the image data from Picnik's servers; the second hit is a GET when the user's browser is redirect back to your website.

Debugging this kind of interaction can be tricky. Take a look at the King of the Hill sample to see how this kind of interaction works.

Next Steps

Start coding! You'll probably want to keep a link to the reference section handy. And of course, you can always go back and take a look at all the tutorials.