TracNav
FAQ
While developing the Hyves API, we decided that everything should be self-explaining. If we succeeded in that, the section below will stay mostly empty :); when questions arise, we will handle them here.
- general
- How do i fix the error "OAuth timestamp is invalid"?
- secrets or encoding errors
- IDs
- Usernames
- Media URLs
- User contact information
- When do I use a POST or a GET?
general
If you receive an error, first check in this list what possible causes en solutions are for this error. Hopefully those descriptions should put you on your way to the solution.
How do i fix the error "OAuth timestamp is invalid"?
This means your own server-time is not set correctly or is not syncing properly. See Unix time.
secrets or encoding errors
Especially errors with calculation of secrets, should benefit from the descriptions of content encoding. If you have problems with secrets, please check our examples, and see if your code behaves the same way for each example. The examples were taken from http://wiki.oauth.net/TestCases, and most of them serve as unit tests for us.
Another problem that we encountered, is that PHP (or the browser?) translates http://data.hyves-api.nl to http://data.hyves-api.nl/ (note the final slash). If the Consumer calculates the oauth_secret on the basis of an URI without the final slash, and the Service Provider does include the final slash, the secrets will not match. So make sure that you always have your URI end in a slash.
You can use the API Console to debug secret generation.
IDs
All IDs (userid, mediaid, etc) are the same for every Partner. In the past we provided different IDs for each partner, so maybe you still have to convert your IDs if you are such a partner. you will find this link on http://www.hyves.nl/api/manage/
Version 1.0, 1.1, 1.2 and 1.2.1
IDs are an 8 byte (64bit) integer, encoded as a hexadecimal string of 16 characters, which means they can be stored internally as 64bit unsigned integers. Although the IDs can be saved as 64bit integers, we expect the IDs returned to us to be the exact the same as we supplied them to you - as a 16-character hexadecimal string; this especially means that "low numbers" should be pre-padded with zeros to be 16 characters long. If IDs of any other format are received, they will be treated as non-existing IDs.
Version beta_2 and higher
IDs are an 17 byte (136bit) integer, encoded as a hexadecimal string of 34 characters, which means they can be stored internally as 136bit unsigned integers. Although the IDs can be saved as 136bit integers, we expect the IDs returned to us to be the exact the same as we supplied them to you - as a 34-character hexadecimal string; this especially means that "low numbers" should be pre-padded with zeros to be 34 characters long. If IDs of any other format are received, they will be treated as non-existing IDs.
Something else should be mentioned about IDs: For many objects, for instance media, having the ID enables you to see the object. There is no extra check for security, so it is to the Consumer to make sure that ids retrieved as one user are not automatically shown to another user. See the return values for more information. There is a possibility that we are going to need longer IDs in the (far) future, but such a move will be announced long in advance.
Note: sometimes no id is returned (the field is empty). In this case, no foreign relation is present, or you have insufficient rights to see the id. An example is the userid for the default profile image.
Usernames
The Hyves API allows you to use usernames to retrieve a user. It should be noted that usernames should not be used for anything else. Unlike most websites, Hyves allows users to change their usernames; and they do so regularly. So it would be an especially bad idea to use usernames as primary key for anything; the user with username "john" today, may not be the same as the user with the username "john" tomorrow.
On the Hyves website, the username is not displayed anywhere, except in the URL for the personal overview page. That is why there is no API function to retrieve the username for a user. Although the username can at the moment be deducted from the "url" field of a user, the format of that link may change without notice.
Media URLs
Our image serving system works in such a way that media urls can only be guaranteed for a short period. We suggest caching of media urls for not more than one day.
User contact information
Contact information (e.g. email addresses, phone numbers) will not be available through the API anytime soon. The idea behind this is that there is a huge difference between allowing my friends to see my email address, and allowing applications logged in as my friends to see my email address. I don't trust my friends to be able to decide which applications they trust with my information.
Looking at it from another way: like the rest of the world I receive a lot of spam. This is because my email address was harvested once by a virus on a computer of one of my friends. So again, if I have friends that manage to install virusses on their own PCs, I'm not going to trust them to only allow benevolent applications to see my email address.
Last part of my argument is that in general contact data is needed to contact people. Even applications with the most benevolent intentions can send emails that are perceived spammy by users (I'm sure you've received your fair share of email that was probably sent with the best intentions, but that you really didn't want to receive). So we don't see how we can share contact data while at the same time protecting our users against spam.
If you want contact information on the logged in member, the best way is to just ask them for their email address. I'm sure if they're willing to share that, they won;t mind typing it in.
When do I use a POST or a GET?
With large requests we advise to use HTTP/POST, because with HTTP/GET the querystring is limited to 4k (+/- 4000 characters).
