add and change methods

Author: veselcraft

docs/openvk_engine/api/authorization.md

@@ -1,8 +1,14 @@
+There are two types of authorization. One, that is intended for apps, and second for apps and web applications.
+
+Current OpenVK's official instance is located at https://api.openvk.org/. Don't try to visit this link, it will redirect you back - this domain is made special for API requests because of Anti-DDOS limitations. 
+
 ## Password authorization
 
 To get token, you should call the "token" page:
 
-`{YOUR DOMAIN}/token?username={YOUR USERNAME}&password={YOUR PASSWORD}&grant_type=password`
+`https://{YOUR DOMAIN}/token?username={YOUR USERNAME}&password={YOUR PASSWORD}&grant_type=password`
+
+Replace `{YOUR DOMAIN}`, `{YOUR USERNAME}` and `{YOUR PASSWORD}` to it's proper value.
 
 You'll get a response like this:
 
@@ -14,30 +20,28 @@ You'll get a response like this:
 }
 ```
 
-If you need to call the function that requires a token, just put the `access_token` into your GET or POST request.
+If you need to call the function that requires a token, just put the `access_token` into your GET or POST request, or in HTTP header "Authorization" as Bearer token.
 
-If you have two-factor authorization turned on, add a `code` field to your POST request and fill it with, you guessed it, authorization code.
+If you have two-factor authorization turned on, either sumbit the code via `request_uri` in Web or pass the 2FA code to the `code` field.
 
-**Client name**
+### Client name
 
-At this moment, OpenVK API apps are not implemented. But you can set client name for your token: for this, pass `client_name` param at token page:
-
-`{YOUR DOMAIN}/token?username={YOUR USERNAME}&password={YOUR PASSWORD}&grant_type=password&client_name={YOUR CLIENT NAME}`
-
-This name will be seen in some parts of site (online mark and post).
+At this moment, OpenVK API apps are not implemented. But you can set client name for your token: for this, pass `client_name` param at token endpoint. This name will be seen in some parts of site (online mark and post).
 
 ## OAuth
 
 To get token via OAuth, you should call the "authorize" page:
 
-`{YOUR DOMAIN}/authorize?client_name={YOUR CLIENT NAME}&redirect_uri=&display=page&response_type=token&revoke={0|1}`
+`https://{YOUR DOMAIN}/authorize?client_name={YOUR CLIENT NAME}&redirect_uri={REDIRECT URI}&display=page&response_type=token&revoke={0|1}`
+
+You can set any URL at `redirect_uri`. For apps, we recommend setting this to "https://{YOUR DOMAIN}/blank.html".
 
-You can set any URL at `redirect_uri`, but we will set "https://oauth.vk.com/blank.html".
+For passing access_token as HTTP GET parameters, set `response_type` to `php`.
 
 On `revoke`=1 old token will be revoked.
 
 Additional params: `prefers_postMessage`, `accepts_stale`.
 
 ## Token revoking
 
-As api apps are not implemented, you cannot revoke individual token, but you can revoke all tokens at once: for this, go to {YOUR DOMAIN}/settings?act=security -> "End all sessions".
+As api apps are not implemented, you cannot revoke individual token, but you can revoke all tokens at once: for this, go to /settings?act=security -> "End all sessions".

docs/openvk_engine/api/methods/audio/getPlaylistById.md

@@ -0,0 +1,20 @@
+### `audio.getAlbums` 🔰
+
+Fields: **`owner_id`**, **`playlist_id`**
+
+Returns playlist.
+
+**Result**:
+
+|Name|Value|Description|
+|--|--|--|
+|`id`|int|Absolute playlist ID|
+|`owner_id`|int|Owner's ID|
+|`raw_id`|string|Prettyfied ID|
+|`title`|string|Playlist's name|
+|`cover_url`|string|URL to covers|
+|`last_updated`|string|Date when playlist was updated|
+|`explicit`, `followed`, `official`, `listens`|int|Dummies, always 0|
+|`size`|int|Count of tracks in playlist|
+|`covers` and `list`|array|Dummy, currently empty|
+|`description` and `raw_description`|array|Playlist description|

docs/openvk_engine/api/methods/audio/getPlaylists.md

@@ -0,0 +1,3 @@
+### `audio.getPlaylists` 🔰
+
+Alias of [audio.getAlbums](getAlbums.md).

docs/openvk_engine/api/methods/execute.md

@@ -0,0 +1,48 @@
+### `execute` 🔰
+
+Execute method. Javascript-like scripting language, where you can make up to 25 API calls to generate complex results in one go. Server will compile your code and execute it.
+
+Scripting language support this features:
+
+* Arithmetic operations: `+` `-` `*` `/` `%`
+* Variables: `var a`
+* Conditions: `if`, `else`
+* Loops: `while`, `for`, `break`, `continue`
+* Object and array literals: `{key: "value", 'another_key': 123}`, `['a', 123, {}, someVariable]`
+* API calls: `API.method({parameters})`
+* Object array field selection operator `@.`.
+* Functions: `parseInt` and `parseDouble`
+* Methods on arrays: `push`, `pop`, `slice`, `splice`, `shift`, `unshift`, `indexOf`
+* Methods on strings: `substr`, `split`, `indexOf`
+* The `.length` property on strings and arrays
+* The special `Args` object that contains any extra parameters you passed to this method
+* The `delete` operator to remove fields from objects, e.g. `delete groups[i].description;`
+* `//` and `/* ... */` comments
+
+### Code examples
+
+Get posts and notes count for user:
+
+```
+var p=API.wall.get({owner_id:1});
+var n=API.notes.get({user_id:1});
+return [p.count,n.count];
+```
+
+Get likes and comments counts from photo:
+
+```
+var p=API.photos.getById({"photos":"1_136","extended":1}); 
+return {"pid":p@.id,"likes":p@.likes,"comments":p@.comments,"can_comment":p@.can_comment,"tags":p@.tags};
+```
+
+Check if user can post on wall:
+
+```
+return API.wall.getById({"posts":"1_164"})[0].comments.can_post;
+```
+
+### References
+
+* https://web.archive.org/web/20150429005235/http://vk.com/dev/execute
+* https://smithereen.software/docs/api/methods/execute

docs/openvk_engine/api/methods/newsfeed/getRecommended.md

@@ -0,0 +1,5 @@
+### `newsfeed.getRecommended` 🔰
+
+Alias of [newsfeed.getGlobal](getGlobal.md). 
+
+Official clients can access global feed by just simply switching newsfeed type to Recommendations.

docs/openvk_engine/api/methods/photos/get.md

@@ -3,3 +3,5 @@
 Fields: **`owner_id`**, **`album_id`**, `photo_ids`, `extended`, `photo_sizes`, `offset`, `count`
 
 Returns a list of photos inside the album.
+
+For default avatar's album, set `album_id` to `profile`.

docs/openvk_engine/api/methods/polls/addVote.md

@@ -1,5 +1,7 @@
 ### `polls.addVote` 🔰
 
-Fields: **`poll_id`**, **`answers_ids`**
+Fields: **`poll_id`**, **`answer_ids`** or **`answer_id`**
 
 Adds a vote to poll.
+
+`answer_ids` is separated by comma.

docs/openvk_engine/api/objects/audio.md

@@ -13,7 +13,7 @@
 | keys    | Array   | Keys for manifest.  |
 | genre_id    | int   | Genre id of the track.  |
 | genre_str    | string   | String with genre name.  |
-| lyrics    | int   | You can get actual lyrics by `audio.getLyrics`.  |
+| lyrics_id    | int   | Return current audio if if Lyrics exists. You can get actual lyrics by `audio.getLyrics`.  |
 | added    | bool   | Does the user's collection contain this audio??  |
 | editable    | bool   | Can audio be edited by current user?  |
 | searchable    | bool   | Is it possible to find audio in search?  |

docs/openvk_engine/api/objects/user.md

@@ -14,22 +14,35 @@
 |`status`|string|Status. If user have audiostatus, returns `status_audio`|
 |`screen_name`|string|Users shortcode|
 |`friend_status`|int|-|
-|`last_seen`|int|User last online|
+|`online`|int|Is user online. Also adds `mobile_online` if user is online from mobile|
+|`last_seen`|object|Object with `platform` (check below) and `time` with user's last time activity|
 |`music`|string|Users favourite music|
 |`movies`|string|Users favourite films|
 |`tv`|string|Users favourite tv shows|
 |`books`|string|Users favourite books|
-|`city`|string|Users city|
+|`city`|object|Object with `id` (always zero) and `city`, which, well, contains user's city|
 |`interests`|string|Users interests|
 |`quotes`|string|Users favourite quotes|
 |`email`|string|Users contact email|
 |`telegram`|string|Users telegram|
 |`about`|string|Users description|
 |`rating`|string|Users rating|
-|`correct_counters`|array|Array with user's counters|
+|`counters` or `correct_counters`|array|Array with user's counters|
 |`background`|array|Background photo urls|
 |`reg_date`|int|User registration date|
 |`is_dead`|bool|Is user dead|
 |`nickname`|string|Nickname, or "middle name"|
 |`blacklisted_by_me`|bool|Is blacklisted by current user|
 |`blacklisted`|bool|Is this user blacklisted me|
+
+## Platforms
+
+| Id | Name | Description |
+|---|---|---|
+|1	|`mobile` | Mobile app |
+|2	|`iphone` | App for iPhone|
+|3	|`ipad` | App for iPad __Currently not used__|
+|4	|`android`|	App for Android|
+|5	|`wphone`| App for Windows Phone. __Currently not used__|
+|6	|`windows`|	App for Windows 8. __Currently not used__|
+|7	|`web`	|Website or unknown app|