Picnik: API Documentation

Picnik API Documentation » tutorials » making-the-call

Making The Call

The ins and outs of invoking the Picnik API

The Basics

To ask Picnik do something, you make a call to a specially formatted URL. This URL always starts with http://www.picnik.com/service/. You will add additional parameters to this URL which tell Picnik what to do.

There is one required parameter: _apikey. This parameter uniquely identifies your application and must always be present. All other parameters are optional.

The names of Picnik API parameters begin with an underscore. Any parameters you send which do not begin with an underscore will be sent back to you (with the same values you originally specified) when the user is sent back to your website. You can use these custom parameters to maintain state, coordinate server operations, or anything else you like.

To GET or to POST?

You can use either HTTP GET or HTTP POST to invoke the API. Which you choose will depend on the needs of your application and personal preference. For example, these two HTML snippets both do the same thing:

<a href="http://www.picnik.com/service/?_apikey=YourApiKey">Go!</a>

<form action="http://www.picnik.com/service/">
	<input type="hidden" name="_apikey" value="YourApiKey"/>
	<input type="submit" value="Go!"/>
</form>

Some API parameters require either HTTP POST or HTTP GET to work correctly. If you're using HTTP GET, keep in mind that URLs have a practical length of 2,083 characters (see this note from Microsoft). However, the vast majority of Picnik API calls will use much shorter URLs and this length should not be an issue.

If you're passing URLs to Picnik via HTTP GET, don't forget to encode them first (for example, using PHP's rawurlencode or Javascript's encodeURIComponent).

The Easiest Integration Ever

Just for fun, let's take a look at a sample. This demonstrates one of the simplest and most useful Picnik integration scenarios: by using the _import parameter, we can specify an initial image for editing.

Load This Image Into Picnik!

Here's the link we're using:

http://www.picnik.com/service/?_apikey=YourApiKey&_import=http%3A//www.picnik.com/graphics/api/api_sample_1.jpg

Let's take a look at that URL more closely.

First, calls to the Picnik API always begin with http://www.picnik.com/service/. That's an easy one.
Next, all calls to the Picnik API need to provide an _apikey parameter. (Don't have an api key yet? What are you waiting for?)
Finally, we use the _import parameter to tell Picnik to load a specific image for editing.

That's all there is to it! But of course, that's not all that Picnik can do...

Next Steps

From here you might want to learn more about sending images in to Picnik. Or perhaps you'd like to learn how to customize Picnik's UI? And of course, you can always go back and take a look at all the tutorials.