Getting started with the API

A summary of the main things you need to know to use the ipernity API. Each point is detailed in other available documentation.

Glossary

To begin, let us agree on some terms:

• API Key: this is a unique key provided free of charge and that identifies your application.
• Secret: a secret you use to sign your API requests.
• API method: a method is a function of the API.
• Sign requests: a request is authenticated with your secret. This ensures its origin.
• Authorized: when a member wishes to use your application to access his private data, he must give his permission. This allows the application to act on his behalf.

Get your API key

Your API key uniquely identifies your application. This key will be requested every API call. Note that each key is accompanied by a secret. This code will allow you to sign your API requests and ensure their authenticity. The API keys are free but subject to the acceptance of the ipernity API Terms and Conditions of use. Would you like to get your key now?

Who can use your application?

It's up to you to decide. You might want to keep your application secret, or benefit from a wide audience. During development, please keep your key active but hidden. Statistics are available to monitor the activity of your application.

If you want to chat with users of your application, create a group and link it to your application.

What is an API request?

The API is a web service that responds to the HTTP protocol on the url http://api.ipernity.com/api. Applications may be sent by GET or POST. Here we have the classic example of hello world.

http://api.ipernity.com/api/test.hello/xml?api_key=6fa87ba(..)fe457

Items in the following url are:

• test.hello : the name of the API method called. (test.hello)
• xml : the desired output format.
• api_key : the API key.

The response to the request:

<api status="ok">
 <hello>hello world!</hello>
</api>

Requests to modify data must be sent by POST action.

What is the secret?

The secret guarantees the origin and authenticity of API requests. All sensitive methods such as altering data or access to private objects should be signed with the secret. This is not complicated. Take a look at the documentation about encoding and signatures, or be inspired by one development kit.

We advise you to automatically sign your requests. If you must, check calls to the API will always be signed in the settings of your key. This will prevent anyone from using your API key without your knowledge.

Tell me more about authorization

Imagine that your application can modify the tags of documents. A member wishing to use it has to give permission for your application.

Specifically, your application will redirect the member to page showing the required rights it wishes. The member must then approve the access requested. Access rights are granted until the member withdraws the application.

• Read authentication for Web applications.
• Read authentication for desktop applications.

Use the API kit, or write your own

The API kits offer essential functions for using the API. If you can't find what you need you can easily write your own.

Need help?

We created two groups for this subject:

• API dev : The ideal group to monitor developments in the API.
• API users : The group where you can find help or give help to others.