Automating the use of Javascript API Vkontakte

A couple of days ago, as usual, without notifying anyone, Contact added the ability to develop JavaScript applications connected via iframe. Access to the API in these applications is, in general, the same as accessing the API from Flash - anyway, this is the usual REST protocol. Parameters are passed through the GET request string, and the result is returned as JSON or XML.

One of the problems of using the Vkontakte API is to send a cross-domain request to http://api.vkontakte.ru/api.php. Another problem is the cumbersome calculation of the signature, which needs to sign all requests. First of all, I, like many other developers, took up jQuery. However, firstly, using the 68-kilobyte library for the sake of cross-domain queries is like shooting a gun at sparrows. Yes, and somehow cumbersome was a call to API functions using jQuery, so I had to abandon jQuery in favor of a small function for cross-domain queries. Well, in order to somehow simplify my life, I decided to make a small library that would not only load the specified URL with getting the server response, but also perform the most inconvenient API in all this - signature calculation.

The end result can be found by clicking on the links at the end of the article, and I will focus on the individual points of use and implementation.
')
To use the Vkontakte API, you need to connect a file with the library to the HTML document of the application:

<!-- , HTML- --> < script src ="vk_api.js" type ="text/javascript" ></ script > * This source code was highlighted with Source Code Highlighter .

1. <!-- , HTML- --> < script src ="vk_api.js" type ="text/javascript" ></ script > * This source code was highlighted with Source Code Highlighter .
2. <!-- , HTML- --> < script src ="vk_api.js" type ="text/javascript" ></ script > * This source code was highlighted with Source Code Highlighter .
3. <!-- , HTML- --> < script src ="vk_api.js" type ="text/javascript" ></ script > * This source code was highlighted with Source Code Highlighter .

<!-- , HTML- --> < script src ="vk_api.js" type ="text/javascript" ></ script > * This source code was highlighted with Source Code Highlighter .

The library itself is a single vk_api object and the md5 function, honestly borrowed from Webtoolkit. The vk_api object is not ready for use by itself - it is necessary to create an instance from it using the constructor:

1. var api = new vk_api ( / * parameters * / );

* This source code was highlighted with Source Code Highlighter .

In principle, it would be possible to perform all initialization when loading the vk_api.js script itself , but this is not the way of a samurai - what if you don’t have to call the API in this session at all? In addition, during initialization, the constructor is passed parameters that somehow need to be set somewhere and passed to the script.

So, let's try to create an object:

1. // Create an object from vk_api (). All further work must take place.
2. // with api object only.
3. var api = new vk_api (
4. // This is a Secret, it is listed on the application editing page
5. 'hGtsH5G0' ,
7. // This function will be called if the initialization of the API is successful.
8. // Good place to set all callback functions through
9. // addCallback ()
10. function () {
12. // Call the change settings window with the marked settings for
13. // access to friends and to the wall. User will not be able to close
14. // called window until it sets the required settings.
15. api.makeSettings (api.SETT_FRIENDS | api.SETT_WALL);
17. // Add a function that will run if the user adds
18. // application to your page.
19. api.addCallback (
20. 'onApplicationAdded' ,
21. function () {
22. //actions
23. }
24. );
25. },
27. // This function is called if the API initialization failed.
28. // In this case, it is impossible to use external (external) calls.
29. function () {
30. // error message
31. }
32. );

* This source code was highlighted with Source Code Highlighter .

As you can see, everything is very simple. The designer is supposedly given a secret key (aha, the secret one is presented in the page code in an open form) and two functions, the first of which is performed in case of successful initialization and the other in case of an error during initialization. In fact, the second function is not at all necessary if the developer does not want to take into account those isolated cases when an error occurs during initialization. In addition, there is another parameter, which is a normal logical flag, indicating whether the test mode is enabled.

The fact is that in test mode, for each API method called, one more always the same parameter must be added. So, the support of the global one-time inclusion of the testing mode will relieve developers of unnecessary gestures when preparing an application for release - you will need to remove only one designer parameter, instead of editing multiple API calls.

If you look at a couple of dozens of Vkontakte applications, then very many of them require users to install them and allow them to do something. In this case, the applications either simply display a message with instructions on where to go, what to do, or, at best, immediately display the setup or change settings window. Well, it was a sin not to implement such functions at the library level. Moreover, at the request of one person, I went a little further, and implemented these functions in such a way that the user cannot close the window with a proposal to install the application at all or allow him something until he agrees with the requirements of the application. Thus, it is not necessary to provide additional application pages for those users who refused to install or did not allow something to the application - it is enough to simply call one or two functions:

1. // Display a window asking to install the application.
2. api.makeInstall ();
3. api.addCallback (
4. 'onApplicationAdded' ,
6. // This function will be called when the user installs the application.
7. function () {
8. $ ( '#text' ) .append ( 'Application added \ n' );
10. // Ask the user to allow the application to access
11. // to friends and to post on the walls
12. api.makeSettings (api.SETT_FRIENDS | api.SETT_WALL);
13. api.addCallback (
14. 'onSettingsChanged' ,
16. // The function will be executed when the user changes the application settings.
17. function (settings) {
18. $ ( '#text' ) .append ( 'New parameters:' + String (settings) + '\ n' );
19. }
20. );
21. }
22. );

* This source code was highlighted with Source Code Highlighter .

Let us turn, finally, to why the application was developed, i.e., directly to the call of API functions. For this, the call method is provided:

1. // Call the API method via the call () function
2. api.call (
4. // Name of the API method.
5. // Suppose getting extended information about profiles.
6. 'getProfiles' ,
8. // This is an object with API method parameters. If there are no parameters,
9. // then this argument can be omitted.
10. {
11. uids: '4124584,2327412,1237975' ,
13. // You can specify arrays that will be automatically
14. // converted to strings.
15. fields: [
16. 'first_name' , 'last_name' , 'nickname' ,
17. 'bdate' , 'city' , 'country' , 'photo'
18. ]
19. },
21. // This function will be called when a response is received from the server.
22. // data is a ready-to-use object created from a string
23. // JSON received from the server.
24. function (data) {
25. // Actions with the data object
26. }
27. );

* This source code was highlighted with Source Code Highlighter .

As you can see, everything is simple, and no unnecessary actions that we need.

As for the so-called secret key, transmitted to the vk_api constructor by the first parameter, for it I provided the simplest, not even encryption, but encoding. The key in encoded form looks like this: sx - 36l76l11l57l52l14l65l42l56l31l - a variation on the theme of character codes. The first characters of the string sx-- are needed in order to preserve the possibility of transmitting an uncoded secret key to the designer - if the string starts with sx-- , then the key is encoded, otherwise the key is transmitted in clear text. Why such simple coding? Yes, because it is a fool proof, no more. From the young hacker, who just read another article in a well-known magazine, this method will help to protect themselves, and from a qualified developer who knows the basics of JavaScript, no encryption will save, because in the end, the script needs a secret in the clear, and therefore the function to decrypt must be in code.

Actually, there is nothing unusual in the library. But from routine work when developing applications, the library will save. As promised, below is the download link.

Library: vk_api-1.4.4.zip .
Project page on Google Code: http://vk-jsapi.googlecode.com/
New versions and full description .