Data encoding and request signature

Build an API request

An API request is an HTTP request sent to the URL:

http://api.ipernity.com/api/[method]/[format]

• [method]: The API method you want to call.
• [format]: The response format you wish. Format is optional, default value is json.
• The API allows sending parameters using GET and POST.
  All the methods implying modification of data (add/edit/delete) always use POST.

Data encoding

All data must be encoded in UTF-8 format.

We try to detect if you use another charset. So we attempt to convert to UTF-8 (but it's better to use UTF-8 encoding).

Request signature

Some API methods require signature. So ipernity can check whether your application is the requester or not.
To sign a request, you must get an API key (api_key) and a secret code (secret). This secret code must be kept... secret!

The request signature corresponds to the md5 of a string composed of the following parameters concatenated each other without spaces:

• alphabetical ordered parameters followed by their values,
• the called method,
• your API key secret.

For example, if you wish to call doc.tags.add method with the following parameters:

• api_key: 6fa87ba500002712bd4eed6020f3bd72
• secret: e9a599f0cf6ce193
• doc_id: 1234
• keywords: easy

String to be signed will be:

api_key6fa87(...)bd72doc_id1234keywordseasydoc.tags.adde9a599f0cf6ce193

and its md5:

a269b218feb341ef03bc093a0f2c8078

The signed API request will be:

http://api.ipernity.com/api/doc.tags.add/json?api_key=6fa87(...)bd72
&doc_id=1234&tag=easy&api_sig=a269b218feb341ef03bc093a0f2c8078

Missing or invalid signature will cause 104 (missing) or 105 (invalid) error.

Did you know? We propose a signature calculation wizard.

Authorization link signature

Calculation of an authorization link signature is made like calculation of a request signature without specifying an API method name.

For instance, if we like to ask "read" authorization on a user's network, here are the parameters to sign:

• api_key: 6fa87ba500002712bd4eed6020f3bd72
• secret: e9a599f0cf6ce193
• perm_network: read

So the string to sign is:

api_key6fa87(...)bd72perm_networkreade9a599f0cf6ce193

and its md5:

da183021cd39461108770b822fcd9398

Here is the authorization link:

http://www.ipernity.com/apps/authorize?api_key=6fa87(...)bd72
&perm_network=read&api_sig=da183021cd39461108770b822fcd9398

Learn more about authentication for Web applications or authentication for desktop applications.