This module is a simple synchronous/asynchronous wrapper for the vk.com API.

API object initialization

# Synchronous VK API
let api = newVkApi()
# Asynchronous VK API
let asyncApi = newAsyncVkApi()
# If you want to provide a token instead of login and password,
# pass the token as an argument:
let api = newVkApi(token="your token")

Authorization

Authorization is actually done with the vk.com OAuth API and uses secret key and client ID of VK iPhone client.

api.login("your login", "your password")
# You can login if you have 2-factor authentication as well
api.login("your login", "your password", "your 2fa code")
# Async authorization
waitFor asyncApi.login("login", "password")

Synchronous VK API usage

echo api.request("friends.getOnline")
echo api.request("fave.getPosts", {"count": "1"}.newTable)
echo api.request(
  "wall.post", {
    "friends_only": "1",
    "message": "Hello world from nim-lang"
  }.toApi
)

This module also has a @ macro, which can make API requests shorter and look more "native".

Don't forget that this macro DOES NOT actually check if argument types or names are correct!

echo api@friends.getOnline()
echo api@fave.getPosts(count=1)
api@wall.post(friends_only=1, message="Hello world from nim-lang")

Asynchronous VK API usage

import asyncdispatch

echo waitFor asyncApi.request("wall.get", {"count": "1"}.toApi)
echo waitFor asyncApi@wall.get(count=1)

Types

VkApiBase[HttpType] = ref object token*: string ## VK API token version*: string ## VK API version client: HttpType: VK API object base
VkApi = VkApiBase[HttpClient]: VK API object for doing synchronous requests
AsyncVkApi = VkApiBase[AsyncHttpClient]: VK API object for doing asynchronous requests
VkApiError = object of Exception: VK API Error
VkAuthError = object of Exception

Consts

ApiVer = "5.85": Default API version

Procs

proc newVkApi(token = ""; version = ApiVer): VkApi {...}{. raises: [Exception, SslError, OSError, IOError], tags: [RootEffect, ReadDirEffect].}

Initialize VkApi object.

token - your VK API access token
version - VK API version
url - VK API url

proc newAsyncVkApi(token = ""; version = ApiVer): AsyncVkApi {...}{. raises: [Exception, SslError, OSError, IOError], tags: [RootEffect, ReadDirEffect].}

Initialize AsyncVkApi object.

token - your VK API access token
version - VK API version
url - VK API url

proc login(api: AsyncVkApi; login, password: string; twoFactorCode = ""; scope = AuthScope): Future[void] {...}{.raises: [FutureError], tags: [RootEffect, TimeEffect, ReadIOEffect].}

api - VK API object
login - VK login
password - VK password
code - if you have 2-factor auth, you need to provide your 2-factor code
scope - authentication scope, default is "all"

Example of usage:

let api = newVkApi()
api.login("your login", "your password")
echo api@users.get()

proc login(api: VkApi; login, password: string; twoFactorCode = ""; scope = AuthScope) {...}{.raises: [ HttpRequestError, SslError, OSError, IOError, Exception, TimeoutError, ProtocolError, KeyError, OverflowError, ValueError, JsonParsingError, VkAuthError], tags: [ReadIOEffect, WriteIOEffect, RootEffect, TimeEffect].}

api - VK API object
login - VK login
password - VK password
code - if you have 2-factor auth, you need to provide your 2-factor code
scope - authentication scope, default is "all"

Example of usage:

let api = newVkApi()
api.login("your login", "your password")
echo api@users.get()

proc toApi(data: openArray[tuple[key, val: string]]): StringTableRef {...}{.raises: [], tags: [].}

Shortcut for newStringTable to create arguments for request call

proc request(api: AsyncVkApi; name: string; params = newStringTable()): Future[JsonNode] {...}{. discardable, raises: [FutureError], tags: [RootEffect, TimeEffect, ReadIOEffect].}

Main method for VK API requests.

api - API object (VkApi or AsyncVkApi)
name - namespace and method separated with dot (https://vk.com/dev/methods)

Examples:

params - StringTable with parameters
return - returns response as JsonNode object

echo api.request("friends.getOnline")
echo api.request("fave.getPosts", {"count": "1"}.toApi)
api@wall.post(friends_only=1, message="Hello world from nim-lang!")

proc request(api: VkApi; name: string; params = newStringTable()): JsonNode {...}{. discardable, raises: [Exception, ValueError, JsonParsingError, HttpRequestError, SslError, OSError, IOError, TimeoutError, ProtocolError, KeyError, OverflowError, VkApiError], tags: [ReadIOEffect, WriteIOEffect, RootEffect, TimeEffect].}

Main method for VK API requests.

api - API object (VkApi or AsyncVkApi)
name - namespace and method separated with dot (https://vk.com/dev/methods)

Examples:

params - StringTable with parameters
return - returns response as JsonNode object

echo api.request("friends.getOnline")
echo api.request("fave.getPosts", {"count": "1"}.toApi)
api@wall.post(friends_only=1, message="Hello world from nim-lang!")

Macros

macro `@`(api: VkApi | AsyncVkApi; body: untyped): untyped

@ macro gives you the ability to make API calls using much more easier syntax

This macro is transformed into request call with parameters

Also this macro checks if provided method name is valid, and gives suggestions if it's not

Some examples:

echo api@friends.getOnline()
echo api@fave.getPosts(count=1, offset=50)

Module vkapi