Odnoklassniki Rest API

Redirection Notice
This page should redirect to Odnoklassniki REST API.

Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History

General information

Server Address is passed to the Web applications in "api_server" parameter.

Common request parameters

Name Required Type Description
application_key Y String The application key associated with the calling application. If you specify the API key in your client, you don't need to pass it with every call.
call_id N Long The request's sequence number.
sig Y String An MD5 hash of the current request and your secret key, as described in the Authentication and Authorization section .
format N String Format of method response, can be JSON ot XML. If not specified, HTTP Accept header will be used to determine the format (application/xml or applcation/json).
session_key - String The session key of the logged in user. Session key can be required, optional or prohibited depending on method.

Data protection

  • User, group, album and other ID's are returned as String (this can be changed by request). User IDs for different applications are not the same by default.

Authentication and Authorization

Application configuration

Application has 2 keys associated:

  • Public key is used to identify application.
  • Secret key is used to verify application requests. Developer must use the key to sign requests,

which are passed without session context.

Parameters passed to the application
  • logged_user_id - ID of the authorized user, which is permanent and will not change for the application. We may expose not the real IDs, but encoded with the key.
  • api_server - API server base URL, for example http://api.odnoklassniki.ru/ or
  • application_key - application public key
  • session_key - ID of the user+application session
  • session_secret_key - secret key issued to the application, which must be used to sign all session related requests.
  • authorized - 1 if user authorized your application, or 0 otherwise
  • apiconnection - connection name, passed to ActionScript/JavaScript API
  • sig - An MD5 hash of the current request and your secret key, as described in the Authentication and Authorization section .

Application session identified by the session_id is temporary and generated per application.

Calculating signature
  • Sort the array alphabetically by key.
  • Concatenate all key/value pairs together in the format "k=v" (omitting the signature itself, since that is what we are calculating).
  • Append your secret key, which you can find by going to the Developers application and following the link for your application.
  • Take the md5 hash of the whole string.
  • Make it lower case
Method invocation:
  • All server side requests contain "application_key"
  • Most of client side requests contain "session_key".
  • All requests are signed by the application or session secret key, passed in "signature" parameter.
Authentication error handling
  • After session becomes unavailable, application will get an error trying to call session related method. Application should redirect user back to portal for authentication.

Error codes

Name Code Description
UNKNOWN 1 Unknown error
SERVICE 2 Service temporary unavailable
METHOD 3 Method does not exist.
REQUEST 4 Failed to process request due to invalid request
PERMISSION_DENIED 10 Permission denied. Possible reason - user not authorized application to perform operation
PARAM 100 Missing or invalid parameter
PARAM_API_KEY 101 Parameter application_key not specified or invalid
PARAM_SESSION_EXPIRED 102 Session key is expired
PARAM_SESSION_KEY 103 Invalid session key
PARAM_SIGNATURE 104 Invalid signature
PARAM_USER_ID 110 Invalid user ID
PARAM_PERMISSION 200 Application can not perform operation. In most cases, caused by access to operation without user authorization
PARAM_APPLICATION_DISABLED 210 Application is disabled
AUTH_LOGIN 401 Authentication failure. Invalid login/password or authentication token or user is deleted/blocked.
SESSION_REQUIRED 453 Session key was not specified for the method, which requires session
NO_SUCH_APP 900 Returned, when try to get public application information for not existing application
SYSTEM 9999 Critical system error. Please report these problems support

Error code and message returned as XML or JSON, depending on format. In addition, HTTP header invocation-error contains error code.

Examples


XML
JSON

Callbacks

Application must specify the callback URL to access some platform functions, like Payment Processing.
Callback will be always invoked with the following parameters:

method Y String Callback name
application_key Y String The application key associated with the calling application.
call_id N Long The request's sequence number.
sig Y String An MD5 hash of the current request using application private key, as described in the Authentication and Authorization section .
  • All callbacks for now work through HTTP GET and support only XML responses. Content types must be application/xml
  • Server may return error, using the format described above. List of supported error codes, listed for every callback
  • Firewall must allow incoming connections from : 62.105.140.205, 62.105.140.206, 213.221.38.13, 213.221.38.14

Support

Application can specify the support URL to report issues directly from the portal help screen.
User will be redirected to this URL with the following parameters:

application_key String The application key associated with the application.
uid String ID of user, reporting the problem
name String Full name of user, reporting the problem
first_name String First name of user, reporting the problem
last_name String Last name of user, reporting the problem

Method List

auth.login
auth.loginByToken
auth.expireSession
friends.get
friends.getOnline (Not yet available)
friends.getAppUsers
friends.getBirthdays (Not yet available)
users.getLoggedInUser
users.getInfo
users.setStatus (Not yet available)
photos.getUploadUrl (Not yet available)
photos.upload (Not yet available)
events.getTypeInfo
events.get
stream.publish (Not yet available)
notifications.send (Not yet available)

Callback List

callbacks.payment

auth.login

Login using user name and password and returns session information. Application is not authorized to use this method by default.

Parameters
Name Required Type Description
user_name Y String User name
password Y String Password
gen_token N boolean Default : false. Generate permanent authentication token, which can be used with auth.loginByToken. Authentication token allows implementing Rememeber Me functionality without storing password in application. Token expires, when user changes password in the portal.
Authorization
  • Must be invoked without session
Examples

Request : /auth/login?application_key=[Application Key]&sig=[Signature]&user_name=test&password=test_pwd&gen_token=true

XML
JSON

auth.loginByToken

Login using user authentication token and returns session information. Application is not authorized to use this method by default.

Parameters
Name Required Type Description
token Y String Authentication token generated with auth.login
Authorization
  • Must be invoked without session
Examples

Request : /auth/loginByToken?application_key=[Application Key]&sig=[Signature]&token=afhdjkasdsgsdgshf

XML
JSON

auth.expireSession

Expires user session, created by auth.login or auth.loginByToken

Parameters

No parameters

Authorization
  • Must be invoked within session
Examples

Request : /auth/expireSession?application_key=[Application Key]&sig=[Signature]&session_key=[Session Key]

friends.get

Returns users' IDs of the current user's friends. The current user is determined from the session_key or uid parameters.

Parameters
Name Required Type Description
uid N String The user ID for the user whose friends you want to return. Specify the uid when calling this method without a session key.  
Authorization
  • User must authorize the calling application
Examples

Request : /friends/get?application_key=[Application Key]&sig=[Signature]&session_key=[Session Key]

XML
JSON

friends.getOnline

Returns users' IDs of the current user's friends, who are currently online . The current user is determined from the session_key or uid parameters.

Parameters
Name Required Type Description
uid N String The user ID for the user whose friends you want to return. Specify the uid when calling this method without a session key.
online N String One of : web, wap, mobile. If specified, only users online at the specific portal are retrieved
Authorization
  • User must authorize the calling application
Examples

Request : /friends/get?application_key=[Application Key]&sig=[Signature]&session_key=[Session Key]

XML
JSON

friends.getAppUsers

Returns users' IDs of the current user's friends, who are authorized the calling application. The current user is determined from the session_key.

Authorization
  • User must authorize the calling application
Examples

Request : /friends/getAppUsers?application_key=[Application Key]&sig=[Signature]&session_key=[Session Key]

XML
JSON

friends.getBirthdays

Returns users' IDs of the current user's friends, who have birthday today or in the nearest future . The current user is determined from the session_key or uid parameters.

Parameters
Name Required Type Description
uid N String The user ID for the user whose friends you want to return. Specify the uid when calling this method without a session key.
future Y Boolean If false - returns only friends having birthday this day, otherwise returns users having birthday during next couple days/weeks .
Authorization
  • User must authorize the calling application
Examples

Request : /friends/getAppUsers?application_key=[Application Key]&sig=[Signature]&session_key=[Session Key]

XML
JSON

users.setStatus

Sets or clears user's status with optional geographic location

Parameters
Name Required Type Description
uid N String The user ID for the user whose status you want to change. Specify the uid when calling this method without a session key.
status N String Status text. If not specified, status will be reset (Location ignored) .
location N String JSON encoded Geographic location.
Authorization
  • User must authorize application and grant set_status permission
Examples

Request : /users/setStatus?application_key=[Application Key]&sig=[Signature]&session_key=[Session Key]&status=Working&location={"latitude":45.0,"longitude":-45.0}

XML
JSON

users.getLoggedInUser

Returns information about currently logged in user

Parameters

NO

Examples

Request : /users/getLoggedInUser?application_key=[Application Key]&sig=[Signature]&session_key=[Session Key]

XML
JSON

users.getInfo

Returns a wide array of user-specific information for each user identifier passed.

Parameters
Name Required Type Description
uids Y String The list of coma separated user ID's . The max number of IDs is 100.
fields Y String The list of coma separated field names

Available field names:

  • uid
  • first_name
  • last_name
  • name
  • gender
  • birthday - (yyyy-MM-dd)
  • age
  • locale - (en, lv, ... [language[_territory][.codeset][@modifier]] )
  • location
    • city
    • country
  • current_location (geographical location)
    • latitude
    • longitude
  • current_status
  • pic_1
  • pic_2
  • pic_3
  • pic_4
  • url_profile
  • url_profile_mobile
  • url_chat
  • url_chat_mobile
Authorization
  • Only limited subset of fields is available for users, which haven't authorized the application: uid, first_name, last_name, name, url_profile, url_profile_mobile, url_chat, url_chat_mobile
Examples

Request : /friends/get?application_key=[Application Key]&sig=[Signature]&session_key=[Session Key]&uids=AAA,BBB&fields=first_name,last_name,current_location,gender,pic_1,pic_2

XML
JSON

photos.getUploadUrl

Returns base URL used for photo upload. Can return null, if same server should be used, otherwise returns base part of URL, which must be used to call photos.upload

Name Required Type Description
uid N String The user ID for the user whose status you want to change. Specify the uid when calling this method without a session key.
aid N String Album ID. If null, photo will be uploaded to the user personal photo album. If album ID is application, than photo will be uploaded to the application album of the specified user.
Examples

Request : /users/setStatus?application_key=[Application Key]&sig=[Signature]&session_key=[Session Key]&status=Working&location={"latitude":45.0,"longitude":-45.0}

XML
JSON

photos.upload

Upload one or more photos, with ability to specify caption and geographic location for each photo.

Parameters
Name Required Type Description
uid N String The user ID for the user whose photo you want to upload. Specify the uid when calling this method without a session key.
aid N String Album ID. If null, photo will be uploaded to the user personal photo album. If album ID is application, than photo will be uploaded to the application album of the specified user.
photos Y String JSON encoded list of additional information about uploaded photos, see PhotoUpload
file_* Y Bytes Raw content of uploaded image. Multiple images can be specified as file_1, file_2, etc.

Important: Upload requests must be formed as a MIME multi-part message sent using POST data. File content MUST be specified as a separate chunk.
Other parameters can be specified as query parameter in URL or as separate chunks.

PhotoUpload

Additional information about uploaded photo, contain fields:

  • caption
  • location
    • latitude
    • longitude
Examples


Request


XML
JSON

events.get

Returns events need to be displayed for the logged user. The response contains the following information:

  • user ID
  • type of event
  • number value
  • URL - navigates to the screen associated with the event
  • ID of message to display - text can be retrieved using events.getTypeInfo
  • ID of icon to display - text can be retrieved using events.getTypeInfo
Parameters
Name Required Type Description
uid N String The user ID for the user whose events you want to receive. Specify the uid when calling this method without a session key.
types N String Coma separated list of event types, for which information is requested. Information for all types will be returned, if this parameter is empty.

Currently available types are :

  • discussions
  • guests
  • messages
  • marks
  • notifications
  • activities
Authorization
  • Session is optional
  • User must authorize application
Examples

Request : /events/get?application_key=[Application Key]&sig=[Signature]&session_key=[Session Key]&types=messages,guests

XML
JSON

events.getTypeInfo

Returns display information about event types: name, icons, messages, ...

Parameters
Name Required Type Description
types N String Coma separated list of event types, for which information is requested. Information for all types will be returned, if this parameter is empty
Authorization
  • Does not support session
Examples

Request : /events/getTypeInfo?application_key=[Application Key]&sig=[Signature]&types=messages,guests

XML
JSON

URLs contain tokens, which must be replaced with actual values :

stream.publish

This method publishes a post into the user's news and returns ID of the post.

Parameters
Name Required Type Description
uid N String The user ID. Specify the uid when calling this method without a session key.
message N String The message the user enters for the post at the time of publication.
attachment N String A JSON-encoded object containing the text of the post, relevant links, a media type (image, mp3, flash), as well as any other key/value pairs you may want to add.
action_links N String A JSON-encoded array of action link objects, containing the link text and a hyperlink.
Authorization
  • User must authorize an application and grant publish_stream permission
Examples

Request : /stream/publish?application_key=[Application Key]&sig=[Signature]&message=User entered text&attachment=[Attachment]&action_links=[Action links]
where

Attachment


Action links


XML
JSON

notifications.send

Sends a notification to a set of users. There are two types of notifications: user-to-user and application-to-user notifications. A user-to-user notification is sent on behalf of one user to one or more other users and requires the sending user's active session (with the same allocation amounts as today).
Application-to-user Notifications are sent on an application's behalf and do not require an active session.
User-to-user notifications requires session
This method returns a comma separated list of the recipients who were successfully sent notifications.

Parameters
Name Required Type Description
type N String Either app_to_user or user_to_user (default). If sending user-to-user notification, session is required
to_ids N String Comma-separated list of recipient IDs. These must be either friends of the logged-in user or people who have authorized your application. If this parameter is empty, notification will be send to the currently logged in user.
notification Y String The content of notification using Forticom Markup Language.
Authorization

Application-to-user Notifications - recipient must authorize your application
User-to-user - user A can sent notification to user B if:

  • User A is an application user, and is friends with User B, who is also an application user.
  • User A is an application user, and is friends with User B, who is not an application user.
  • User A is an application user, and is not friends with User B, but both are application users.
Examples

Request : /notifications/send?application_key=[Application Key]&sig=[Signature]&to_uids=AAAA,BBB&notification=Test notification!

XML
JSON

callbacks.payment

Callback, invoked by the API to notify remote application server about completed transaction. Request is signed with the application private key. [More details]

Useful Information
Callback invoked 3 times, until successful HTTP response received. Each retry has 5 sec. timeout. If server does not respond, transaction will be rolled back and virtual money returned back to user.
Parameters
Name Required Type Description
uid Y String User ID
transaction_time Y DateTime Time of transaction
transaction_id Y String Unique ID of transaction
product_code Y String Product code
product_option N String Code of product option selected
amount Y Integer Total amount in virtual currency of the portal
Error codes
Name Code Description
UNKNOWN 1 Unknown error
SERVICE 2 Service temporary unavailable
CALLBACK_INVALID_PAYMENT 1001 Payment is invalid and can not be processed
SYSTEM 9999 Critical system failure, which can not be recovered
PARAM_SIGNATURE 104 Invalid signature
Examples

Request : method=callbacks.payment&application_key=[Application Key]&call_id=111&sig=[Signature]&uid=AAABX&amount=20&transaction_time=2010-02-23 19:06:55&product_code=IDDQD&transaction_id=2_1266944815214

XML

Forticom Markup Language

Forticom Markup Language includes subset of HTML tags (<b>, <i> ,....) and adds some useful tags:

application-name Renders the application name.
if-is-app-user Displays the enclosed content only if the specified user has accepted the
terms of service of the application (that is, authorized your application).
else Handles the else case inside any If
name Renders the name of the user specified, optionally linked to his or her profile.
profile-pic User's profile picture with possible link to user's profile.
time Renders the date and time in the user's time zone
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Redirection Notice
This page should redirect to Odnoklassniki REST API.