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, we like to ask the authorization to access in read only mode the user's contact list, 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.