1. Methods and objects
2. Application registration
3. User authorization
4. Access rights
5. What’s next?

In this manual, you will find the basic information regarding VK’s API working principles and how to use it. If you have already worked with our API or with similar services from other platforms, and you know which app you want to create, we recommend that you go to any applicable documentation section.

API (application programming interface) – This is an intermediary between the app’s developer and some environment with which this app should interact. This API makes it easy to create a code because it provides a set of defined classes, functions and structures for working with your data.

API VKontakte – This interface allows information to be received from the database vk.com with the help of http-requests to the special server. You do not need to know in detail how the base is constructed and from which table and field types it consists of. It is enough that API-request “knows” it. The request syntax and the type of data being returned are strictly determined by the service itself.

For example, to receive data about the user with the ID number “210700286”, you need to make a request of this type:

https://api.vk.com/method/users.get?user_id=210700286&v=5.52

Let’s have a look at the individual parts:

• https:// - connection protocol
• api.vk.com/methods — API server address
• users.get — name of API VKontakte’s “method”. Methods represent conditional commands that correspond with an operation from the database to receive, record or delete information. For example, users.get is a method to receive information about a user, video.add is a method to add a video to your list, likes.delete is a method for deleting the “Like” mark.
  
  All methods are divided by section. For example, to work with communities, you need methods from the “groups” section, methods from “photos” to work with photos, and so on. There is a full list of methods available by section on this page.
• ?user_id=210700286&v=5.52 – parameter request. After naming the method, you need to transfer its entry data (if it has it) - as usual, GET-parameters in http-requests. With our example, we tell the server that we want data about the user with id=”210700286” and that the format of this data should correspond with the API version 5.52 (regarding versions, we’ll speak about that a little later). The entry parameter always lists the page with a description of the method.

In its response, the server returns JSON-object with the requested data (or a message about a mistake if something went wrong). JSON is the format for how data is reported in the format of “Characteristic Name”: “Value”. If you have not used this format before, we recommend that you acquaint yourself with it before you continue reading: JSON, Wikipedia

The response to our request looks like this:

{"response":[{"id":210700286,"first_name":"Lindsey","last_name":"Stirling"}]}

The response structure of each method is also fixed, and while working with API, you know beforehand that you will receive a number in the “id” field and a line in the “first_name” field. These rules are explained on the pages with method descriptions and corresponding objects, which are returned in the response. For example, users.get is where the method’s entry parameters and the structure of its response are described. In fields, you can get the detailed description of each object field from the response.

<!—If you already have experience of working with JSON, you can find useful information about the JSON structure of API VKontakte: JSON structure API VKontakte.-->

The object from the response may not be unique for a specific method. For example, user object has a set of fields which contain data about a user’s education, age and interests can be returned in the response from the methods users.get, users.search, groups.getMembers and others.

In our example, we used the method users.get. To use this method, you only need to input the entry parameters. But usually it won’t be enough. You must register your app in order to use all the capabilities of API VKontakte.

Open the page “Managed apps” in the left menu, then press “Create an app”. You will be directed to the page https://vk.com/editapp?act=create.

You need to choose one of three types of apps:

• Standalone-app – this is an API_ID for mobile or desktop clients from external sites where work with API will use Javascript. The general idea is that requests for API should be implemented with user devices. In this type of application interface, SDK settings and activation certificates for push notifications are available.
• Website – Register API_ID for an external website and work with API from the server. For example, if you want to write script in PHP while using API VKontakte, you need exactly this option.
• IFrame/Flash application – these are the exact applications which you can find in our catalog https://vk.com/apps. They can be downloaded directly to the VK (Flash) server or embedded into the frame of an external website.

If you are still uncertain about which type of app you want to create, choose the first type (“Standalone”).
After confirming the action, you will be redirected to the page with information about the app. Open the page “Settings” in the left-hand menu and you will see the field “ID applications”, in which a number will be located. For example, 5490057. This number is the application identification, a.k.a. “’API_ID”’, “’APP_ID”’, “’client_id”’, and you will need it for your future work.

VK is a social network where there are friendly connections, user-friendly settings and blacklists. A lot depends on who is looking at your page: someone can see everything on your page and others can see only what you allow publicly.

In our API, this principle remains. If your hide a list of your groups from non-friends, then courtesy of the API your non-friends should not see it. Therefore, almost all methods require user authorization in order to begin working. Strictly speaking, the server must know who is asking for the information so as to give it in this same form as on the main version of the website.

In general, for API identification, a special access key is used which is called access_token. This token is a string of numbers and Latin letters which you send to the server along with the request. From this string, the server receives all the necessary information. There are different ways for receiving a token, moreover, it can be given not only to the user but to the community, and the app itself. You can learn more about this here.

We will use the easiest way (Implicit flow) and receive the token for work with API from the app you created during the previous stage.

Open a new page in your browser and enter this URL into the address bar:

https://oauth.vk.com/authorize?client_id=5490057&display=page&redirect_uri=https://oauth.vk.com/blank.html&scope=friends&response_type=token&v=5.52

You must change the number “5490057” in the request to the API_ID of your app.

Press Enter. The window with the correct request will open. It will have the name of the app, access rights icons and your full name.

Press “Allow”. You will be redirected to a new page with a warning that the token must not be copied or given to a third party. In the address bar, there will be the URL https://oauth.vk.com/blank.html, and after it a #. You will see the additional parameters – access_token, expires_in and user_id. The token may look like this:

51eff86578a3bbbcb5c7043a122a69fd04dca057ac821dd7afd7c2d8e35b60172d45a26599c08034cc40a

The token is your access key. While completing certain conditions, a person who received your token may cause significant damage to other people’s data, including yours. That’s why it is very important to not give the token to a third party.

The field expires_in reports the token’s lifespan using seconds. 86,400 seconds equals 24 hours. After 24 hours, the acquired token will stop working. To continue working on your application, you must get a new one. There is a possibility of getting a token that will never expire. For this, add offline in scope. You can forcibly withdraw a token (for example, in the case where its secrecy is compromised) by reducing sessions in your account’s security settings or by changing the password. Also, if speech is happening about a token not from your own app, you can simply delete the app from settings: https://vk.com/settings?act=apps

The field “’user_id”’ contains the id of the user who received the token.

Now you can summon methods using your name. For example, to receive a list of friends who are currently online.

For this, enter this URL into the address bar:

https://api.vk.com/method/friends.getOnline?v=5.52&access_token=

And input your access_token after the “=” sign, then press Enter. In the server response you receive, there will a list of your friends’ ids who are currently online. To get more information about the way this method works, click here. Take note that you did not specify in the request for which user you needed the list. The server used the default information, i.e., your id which it received from the token.

More details about receiving the access key can be found on this page.

As you already know how all the methods are divided into sections, such as friends, photos, video and so on. Each section corresponds to a certain section on the site. Often apps are created to work with a specific section. For example, to view photos or to edit videos. Logically, for an app that only works with a user’s audio player, this app does not require a user’s private messages.

Therefore, the app’s access rights to API are categorized like methods. The app can request access only to communities, or to communities, photos and audio. On this page there is a list of all the access rights in existence, which you can request.

In order to request the rights, use the parameter scope in the authorization dialogue. When you received the token for your app, in scope there was the mentioning of friends value. And in the authorization window, the app requestion access to friends.

Every access right has its own unique name (friends, video and so on) and code (+2, +4, +4096).
In “’scope”’, it is possible to list the names of all necessary access rights (for example, scope = friends,video,photos, and you can enter the sum of their codes (for example scope=22). Every code represents the power of two, and the sum that you got (byte mask). You can always check whether it contains a certain code (cs. account.getAppPermissions).

Some access rights regarding security concerns can be requested only in Standalone apps and only during the process of authorization Implicit Flow. Pay attention to this.

You have now gotten acquainted with the basics of API VKontakte. The rest is up to you.

Of course, in real life, no one works with API in adjacent browser tabs. For this, different programming languages, SDK and code generators are used. The API working mechanism is very simple. The means of sending http-requests and handling responses from the server are practically provided in any environment. This means freedom of choice is constantly existent.