REST API
- All API methods are available through GET and POST requests.
- Every method is available under 2 urls :
- [Server Address]fb.do?method=[method_name] - for example https://api.rbkgames.com/fb.do?method=users.getCurrentUser
- [Server Address]api/[method_group]/[method_name] - for example https://api.rbkgames.com/api/users/getCurrentUser
Server Address is passed to the Web applications in "api_server" parameter.
method can't be passed as an attachment in photo upload methods, but must be passed as query parameter only.
While it is recommended to use "api_server" parameter, you can use the default address for non session requests : https://api.rbkgames.com/.
Common request parameters
| Name | Required | Type | Description |
|---|---|---|---|
| application_key | Y | Integer | The application identifier associated with the calling application. If you specify the API ID in your client, you don't need to pass it with every call. |
| 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, JSON is used. |
| session_key | - | String | The session key of the logged in user. Session key can be required, optional or prohibited depending on method. |
Response format
Response can be obtained in one of the two following formats: XML or JSON, as was mentioned above. If not specified, JSON is used.
There is a certain subtlety that one should keep in mind when calling methods that return lists of data. If the list returned by the method is empty then:
- XML response format: the tag will not contain any elements within itself.
- JSON response format: will return null.
Error handling
If server fails to handle request, HTTP header invocation-error contains error code. In addition response contains details in XML or JSON format.
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 |
| ACTION_BLOCKED | 7 | The requested action is temporarily blocked for current user |
| FLOOD_BLOCKED | 8 | The execution of method is blocked due to flood |
| IP_BLOCKED | 9 | The execution of method is blocked by IP address due to suspicious activity of current user or due to other restrictions applied to given method |
| PERMISSION_DENIED | 10 | Permission denied. Possible reason - user not authorized application to perform operation |
| LIMIT_REACHED | 11 | Method invocation limit reached |
| NOT_MULTIPART | 21 | Not a multi-part request when uploading photo |
| PARAM | 100 | Missing or invalid parameter |
| PARAM_API_ID | 101 | Parameter application_id 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_RESIGNATURE | 105 | Invalid re-signature |
| PARAM_USER_ID | 110 | Invalid user ID |
| PARAM_ALBUM_ID | 120 | Invalid album ID |
| PARAM_WIDGET | 130 | Invalid Widget ID |
| PARAM_MESSAGE_ID | 140 | Invalid message 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 |
| NOT_FOUND | 300 | Requested information is not found |
| EDIT_PHOTO_FILE | 324 | Error processing multi-part request |
| 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 |
| CENSOR_MATCH | 454 | Text rejected by censor |
| FRIEND_RESTRICTION | 455 | Cannot perform operation because friend set restriction on it (put to "black list" or made his/her account private) |
| PHOTO_SIZE_LIMIT_EXCEEDED | 500 | The size in bytes of image binary content exceeds the limits |
| PHOTO_SIZE_TOO_SMALL | 501 | The image size in pixels are too small |
| PHOTO_SIZE_TOO_BIG | 502 | The image size in pixels are too big |
| PHOTO_INVALID_FORMAT | 503 | The image format cannot be recognized |
| PHOTO_IMAGE_CORRUPTED | 504 | The image format is recognized, but the content is corrupted |
| PHOTO_NO_IMAGE | 505 | No image is found in request |
| 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 |
| CALLBACK_INVALID_PAYMENT | 1001 | Error returned by the application server to notify about invalid transaction details |
| PAYMENT_IS_REQUIRED_PAYMENT | 1002 | Payment is required to use service |
| INVALID_PAYMENT | 1003 | Invalid payment transaction |
Error code and message returned as XML or JSON, depending on format. In addition, HTTP header invocation-error contains error code.
Examples
XML
<?xml version="1.0"encoding="UTF-8"standalone="yes"?><ns2:error_response xmlns:ns2="https://api.rbkgames.com/"> <error_code>101</error_code> <error_msg>PARAM_API_KEY : No application ID</error_msg></ns2:error_response>
JSON
{"error_code":100,"error_msg":"PARAM : Either session_key or uid must be specified"}Support
Application can specify the support URL to report issues directly from the application information page.
User will be redirected to this URL with the following parameters:
| application_id | String | The application ID |
| uid | String | ID of user, reporting the problem |
| nickname | String | Nickname 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
