API documentation

← Towards the developers space
About the API
Getting started
Data encoding, signature
Permissions
Authentication for web application
Authentication for desktop application
Authentication with OAuth
API input formats
API output formats
Data formats
Write an API kit

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 user 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 https://api.ipernity.com/api. Applications may be sent by GET or POST. Here we have the classic example of hello world. 

https://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 keywords of photos/videos/docs. A member wishing to use it has to give permission for your application.

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

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.