This documentation describes the YoolinkPro API interface. It's designed for developers who wants to interconnect YoolinkPro with their own applications, or create new application relying on their YoolinkPro account. This documentation does not cover RSS feed export that are explained in the “tool” tab of your YoolinkPro Account, nor it covers the search API. Both of them will be integrated latter in the REST API provided here.
In this section we'll cover the concepts every developer should know before interacting with the API.
The API uses a REST-like interface. This means that our YoolinkPro method calls
are made over the internet by sending HTTP GET, POST, PUT or DELETE requests to
the YoolinkPro API server (http://api.yoolinkpro.com). Nearly any computer
language can be used to communicate over HTTP with the REST server.
Any application that want to use the YoolinkPro API must be able either to
access api.yoolinkpro.com via HTTP (80) or via HTTPS (443).
Before starting developing a YoolinkPro third-party application, an administrator of the YoolinkPro account should ask us to enable the YoolinkPro API support for his account.
When the API support is enabled, three informations are provided to allow the communication between the third-party application and the YoolinkPro API:
api_public_keyThis key will be used to identify the yoolinkpro account which is sending the request. Any request sent must provide that key along with the given parameters.
api_private_keyThis key is private and must not be sent with the request parameters. It's used by the third-party application to sign its requests (as explained below, in the Request Authentication section).
That key is only known by YoolinkPro API and the third-party application, it must be kept secret by the third-party application.
This key is private and must not be sent with the request parameters.
api_admin_keyThat key is used by the third-party application for making privileged
actions. All of the requests for actions described in the Administrator section should be signed with this key, rather than with api_private_key.
First of all, we'll see in this section how to build and send a valid authenticated request to the YoolinkPro API.
In order to make sure a request is sent by the third-party application, YoolinkPro API will perform a signature verification before processing the request.
This section will explain how it works.
The thrid-party application must sign every request it sends. To do so, it has to do build the signature string like the following:
Sort the parameters hash table alphabetically by key.
Concatenate all key/value pairs together in the format "key=value" (omitting the signature itself, since that is what we are calculating).
a_var=a_valueother_var=other_value
Concatenate to the HTTP method string in lowercase (get), the path string (/user/42.json) and the params string created during the previous step.
get/user/42.jsona_var=a_valueother_var=other_value
Append the api_private_key and two mandatory parameters :
X-YP-MilliTimeUnix time in milliseconds, defined as the number of milliseconds elapsed since midnight UTC of January 1, 1970
X-YP-Inta uniq integer or at least a random one
Take the base64 of the SHA1 hash of the whole string.
Note that for all administrator actions, the key to use for signing the request
is not api_private_key but api_admin_key.
Below is a Perl code example that shows how to implement the signing method
sub sign_query {
my $qs = "";
for my $key (sort(keys(%params))) {
$qs .= "$key=".$params{$key};
}
my $string = lc($method) . $path . $qs . $private_key . $millitime . $int;
return Digest::SHA1::sha1_base64($string);
# Important note : we do not append '=' at the end of the signature.
# If your library adds a trailing '=' remove it.
}
Once the signature has been built, the request can be sent to the YoolinkPro API. To do so, all meta-data such as the public key and the signature should be sent via the request headers:
X-YP-AppKeyThis header should contain the api_public_key of the application.
X-YP-SignatureThis header should contain the signature built for the request.
X-YP-MilliTimeThis header should contain the unix time in milliseconds, defined as the number of milliseconds elapsed since midnight UTC of January 1, 1970.
X-YP-IntThis header should contain a uniq integer or at least a random one.
Here is an example of a signed GET request:
GET /user/42.json?a_var=a_value&other_var=other_value
X-YP-AppKey: my_public_key
X-YP-Signature: $sig
X-YP-MilliTime: $millitime
X-YP-Int : $int
Whenever a request is received by YoolinkPro API, it first checks that the signature is valid. To do so, it does the very same process as described above to rebuild the signature, and makes sure both signatures are the same.
If so, the request is authenticated and granted for processing.
Note, the request can played only once and is valid for 30 minutes after $millitime.
All requests performed on the YoolinkPro API should provide a format
argument, as the file extension in the path of the request.
If no format is specified, JSON will be used as the default serialization
format.
Supported formats are : JSON, YAML and XML.
Here is an example of te same request wit different formats:
GET http://api.yoolinkpro.com/users/24.json
GET http://api.yoolinkpro.com/users/24.yaml
GET http://api.yoolinkpro.com/users/24.xml
When an error is triggered, the action will always return a response with the following entries:
error: the error code of the error
message: a message with details about the error that occurs
Checking if error is present in the response object is a good way to check
if the actions succeeded or not.
There are 3 levels of privileges:
Read-only actions (retreiving a link, a user)
Actions executed on the behalf of a specific user (posting in the company's feed).
Actions with administration privileges (creating/revoking users).
When the YoolinkPro API is enabled, another key is given to the client: the
api_admin_key. This key is provided to allow an API request to perform
privileged actions.
This key gives to the application the power of a regular administrator. As a
developer of a third-party application, you should not consider shipping your
application with your api_admin_key (for example if you deploy a desktop app
within your company).
Ideally and if you need it, that key should be prompted to the user (if they are administrator, they have access to the YoolinkPro API information in their account).
All requests for actions described in the section Administrator must been
signed with the api_admin_key.
All the actions described in this section are read-only.
These actions aren't privileged and don't require any identity_token.
This method retreives a user corresponding to the id given.
Returns the user object if found, null object if not.
Parameters
id (*) : the user identifier (integer), given in the path
Response
user: the user oject corresponding to the id
Example
GET /user/42.json
This method retreives a link object corresponding to the id given.
Returns the user object if found, null object if not.
Parameters
id (*) : the link identifier (integer), given in the path
Response
link: the link oject corresponding to the id
Example
GET /link/42.json
All of the actions (except /user/authenticate) described here require an
identity_token. This token is used to execute the action under the
corresponding user's identity.
This token is provided either by /user/authenticate or by the
administrator action /user/identity_token.
This method authenticates a user for a given email and encrypted password.
If the authentication succeeds, returns an identity_token and a bounce url. Return an error object if the authentication failed.
Note that the password must be encrypted with Blowfish with the private key of the application. The following pseudo-code example shows how to encrypt the password:
function crypt_password(clear_password) {
encrypted_data = crypt_string_with_blowfish(clear_password, api_private_key);
return encode_base64(encrypted_data);
}
Parameters
email (*) : the user's email, in plain text
password (*) : the base64 of the password encrypted with Blowfish
Response
identity_token: an identity_token that allows next requests to be executed
on behalf of that user
bounce_url: an URL to bounce the user's browser to in order to
authenticate to the YoolinkPro account.
This method creates a new link object corresponding to the params given in the request body.
Returns the link object if the creation succeeded, null object if not.
Parameters
identity_token (*) : the token identifying the user to use
url (*) : the URL of the link
title (*) : the title of the link
tags (*) : comma-separated list of tags describing the link
description : short message to describe the link
Note that at least one tag is expected. The API won't accept a new link if no tag is given. Hint: you can use your application name as a default tag.
Response
link: return the newly created oject, with an id entry
Example
POST /link.json
url: http://www.example.com/articles/2145232.html
title: Some article
tags: foo,bar,baz
This method retreives the existing link object identified by the id given in the path;
and updates it with the params given in the request body.
Returns the updated link object if the action succeeded, null object if not.
In order to remove an existing value for a given attribute, the attribute must be given with a null value (when an attribute is not given in the request params, its value is untouched).
Parameters
identity_token (*) : the token identifying the user to use
id (*) : the identifier of the link being modified
title : the title of the link
tags : comma-separated list of tags describing the link
description : short message to describe the link
Note that it's not possible to change the URL of an existing link. If you want
to actually change the URL, you have to first DELETE the object and re-create it
with the good URL.
Response
link: return the modified object, with an id entry
Example
In the following example, we alter the link object #42, changing the value
of its attributes title and tags and removing the value of the attribute
description.
PUT /link/42.json
title: Some article, with better title
tags: foo,bar,bazinga
description:
This method deletes the existing link object identified by the id given in
the path.
Returns the deleted link object if the action succeeded, null object if not.
Parameters
identity_token (*) : the token identifying the user to use
id (*) : the identifier of the link being modified
Response
link: return the deleted object
Example
DELETE /link/42.json
In this section, we'll see all the methods available in the YoolinkPro API that
require an api_admin_key.
All the actions must be signed with the api_admin_key rahter than whith the
api_private_key.
These actions are performed with administrator privileges.
This method returns an identity_token for the requested user
Returns the identity_token if authorized and if the user exists, null token if not.
Note that you can use the email address of the user instead of the id
with this action. Other actions refering to a user will need the id though.
An identity_token has a limited time-to-live: it expires 30 minutes after the
last request received with it. If an expired token is used in a request,
a specific error is triggered. this action will have to be used to get a new
token for that user.
Parameters
email or id (*) : the email address or the identifier of the user whose
token is requested.
Response
identity_token: the token corresponding to the user requested
Example
GET /user/identity_token.json?id=42
Creates a new user in the YoolinkPro account.
Returns the created user if succeeded, null user if not.
Parameters
email (*) : email address of the user
firstname :
lastname :
community : a string representing the main SuperTag of the user
Response
user: the newly created user
Example
POST /user.json
email: johan@company.com
firstname: John
lastname: Smith
Update the user if succeeded, null user if not.
As for any resource, in order to remove an existing value for a given attribute, the attribute must be given with a null value (when an attribute is not given in the request params, its value is untouched).
Parameters
id (*) : the identifier of the user
email : email address of the user
firstname :
lastname :
community : a string representing the main SuperTag of the user
Response
user: the user object if the update succeeded
Example
PUT /user/42.json
lastname: Simpson
Disables the requested user. Once disabled, the user woin't be able to access the YoolinkPro account or to use the service anymore.
Parameters
id (*) : the identifier of the user
Response
user: the user object if the update succeeded
Example
DELETE /user/42.json
Enables a previously disabled user. Once enabled, the user is able to check in again to the service.
Parameters
id (*) : the identifier of the user
Response
user: the user object if the action succeeded
Example
PUT /user/enable/42.json
This section describes all the error codes you might receive when using the YoolinkPro API. It's organized by categories corresponding ot the king of error.
Error codes representing failures during request processing.
101. Runtime error
102. Service unavailable
Error codes representing protocol violation
201. The api key is not given (header X-YP-AppKey is mandatory)
202. The signature is not given (header X-YP-Signature is mandatory)
203. Invalid signature
204. Missing parameter
205. Unknown action
Error codes representing failures during resources handling.
301. Unknown resource
302. Create failure
303. Update failure
304. Delete failure
Error codes representing failures during user actions (that needs an identity token).
401. Authentication failed
402. Missing identitiy token
403. Invalid identitiy token
404. Expired identity token
Error codes representing failures during administrator actions (that needs an admin key).
501. Missing Admin Key
502. Invalid Admin Key