[[TracNav(APINav|nocollapse)]]

== Getting started with the Hyves API ==
=== Step 1 ===
Register for a Hyves account. You can choose for a [http://hyves.nl/?module=Corporate&action=showCreateAccount corporate account] or a [https://secure.hyves.org/subscribe/ plain user account]. The difference between these two is that a corporate account isn't attached to a profile on Hyves. When you want to use the API for a company, you need a Corporate Account (there are no companies allowed on a plain user account. When logged in you should go to [http://www.hyves.nl/api/]).

=== Step 2 ===
Apply for an API partner account at http://www.hyves.nl/api/ (Before applying for the API as a corporate member, make sure you are logged in at Hyves with the corporate account). 

=== Step 3 ===
Make a Consumer for your application. This consumer provides your ratelimit for API-calls and contains the IP's of your webserver where your API-calls are coming from. For desktop applications you need to make a Desktop consumer. In most cases you will need a Webconsumer.

=== Step 4 === 
Choose a library to handle the data with the API. You could develop one yourself but the easiest way to start is by using the [wiki:APILibraries libraries] of some of our dedicated developers from the Hyves-API community. In most cases there are some examples provided with these libraries.

=== Note ===
Make sure you take a look at the [wiki:APITroubleshooting troubleshooting and faq] before you have any questions. Else you can post your questions on the [http://hyves-API.hyves.nl hyves-API Hyves].

A Consumer Key is bound to a (software-)application. So, if you run 3 applications on your server that use the Hyves API, you should obtain 3 Consumer Keys.

You can try your newly created Consumer key in the [wiki:APIConsole API Console]. A link will be generated for you that does the API call. If you tick the "Load directly in iframe" box, the link will be called directly in the iframe. This invalidates the link directly: each link can be used only once to avoid a [http://en.wikipedia.org/wiki/Replay_attack replay attack].

Note that the console does not send your Consumer Secret over the internet: the secret is only used within javascript to calculate the [http://en.wikipedia.org/wiki/HMAC HMAC], nothing but the actual API call (if you select "Load directly in iframe") is sent over the internet from that page. Obviously it is your own responsibility to make sure the secret is not cached or stored in your browser, if the browser is shared, or in some other way becomes known to third parties. If you believe your Consumer Secret has become compromised, please [wiki:APIContactUs let us know], and we'll send you a new Consumer Key and Consumer Secret, invalidating your old one (Obviously, this is not true for the applications that run clientside, named [wiki:APIDesktopApplications DesktopApplications] in this documentation). We suggest that you write your code in such a way that the key and secret can be changed easily.

All request tokens and most access tokens are only valid for a short time period, but if you believe that tokens and secret that are valid for a longer period have become compromized, it's your responsibility to [wiki:APIContactUs contact us], so we can revoke the tokens. Note that ''oauth_token''s nor ''oauth_token_secret''s are to be known to anyone else than you and Hyves, not even to the user the token is for (Obviously, this is not true for applications that run clientside, named [wiki:APIDesktopApplications DesktopApplications] in this documentation).

The [wiki:APIConsole API Console] was developed to work under Firefox 2.0.0.x, it may or may not work under other browsers (most likely error would be that the [wiki:APIErrors#errornumber12 oauth_signature is invalid], due to problems in the [wiki:APIEncoding#urlencoding content encoding].)