Java SDK for VK API

Java library for VK API interaction, includes OAuth 2.0 authorization and API methods. Full VK API features documentation can be found here.

This library has been created using the VK API JSON Schema. It can be found here. It uses VK API version 5.199.

1. Prerequisites

• Java JDK 15 or later
• Gradle 7.4.2 or later

2. Dependencies

VK Java SDK uses:

• Apache Http Client version 4.5.13
• SLF4J version 2.0.9
• Apache Commons Lang version 3.6
• Apache Commons Collections version 4.4
• Apache Commons IO version 2.11.0
• Google Gson version 2.9.0

3. Latest release

Latest version:

To add a dependency on VK Java SDK using Maven, use the following:

<dependency>
<groupId>com.vk.api</groupId>
<artifactId>sdk</artifactId>
<version>LATEST_VERSION</version>
</dependency>

To add a dependency using Gradle:

dependencies {
compile 'com.vk.api:sdk:LATEST_VERSION'
}

4. Prepare for using

Create a new VK application here to use VK Java SDK. Please choose an application type depending on which authorization pattern you need. It should be "Standalone" for Direct Authorization, "Web site" for Authorization Code Flow for server side requests and any of them for Client Credentials Flow.

Fill in the title, confirm the action via SMS and you will be redirected to the application settings page.

You will need your application ID (referenced as API_ID in the documentation), secure key (CLIENT_SECRET) and authorized redirect URI (REDIRECT_URI).

5. Logging

VK Java SDK uses SLF4J for logging. If you want to turn on logging, you must include a plugin that bridges SLF4J with a concrete logging framework. See SLF4J documentation.

JDK Logger

Maven:

<dependencies>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>2.0.9</version>
</dependency>
</dependencies>

Gradle:

dependencies {
compile group: 'org.slf4j', name: 'slf4j-api', version: '2.0.9'
}

Add logging.properties file with configuration (located at your src/main/resources path):

.level=INFO
handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level=FINEST
deng.level=FINEST

Set java.util.logging.config.file system property:

-Djava.util.logging.config.file=logging.properties

log4j2

Maven:

<dependencies>
<!-- Binding for Log4J -->
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-slf4j-impl</artifactId>
<version>2.20.0</version>
</dependency>
<!-- Log4j API and Core implementation required for binding -->
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-api</artifactId>
<version>2.20.0</version>
</dependency>
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-core</artifactId>
<version>2.20.0</version>
</dependency>
</dependencies>

Gradle:

dependencies {
//Binding for Log4J -->
compile group: 'org.apache.logging.log4j', name: 'log4j-slf4j-impl', version: '2.20.0'
//Log4j API and Core implementation required for binding
compile group: 'org.apache.logging.log4j', name: 'log4j-api', version: '2.20.0'
compile group: 'org.apache.logging.log4j', name: 'log4j-core', version: '2.20.0'
}

Add log4j2.xml file with configuration (located at your src/main/resources path):

<?xml version="1.0" encoding="UTF-8" ?>
<Configurationstatus="info">
<Appenders>
<Consolename="Console"target="SYSTEM_OUT">
<PatternLayoutpattern="%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %m%n"/>
</Console>
</Appenders>
<Loggers>
<Rootlevel="info">
<AppenderRefref="Console"/>
</Root>
</Loggers>
</Configuration>

6. Initialization

Create VkApiClient object using the following code:

TransportClienttransportClient = newHttpTransportClient();
VkApiClientvk = newVkApiClient(transportClient);

Note that you can use your own transport client. We use Apache Http Client.

7. Authorization

The library provides several authorization flows based on OAuth 2.0 protocol implementation in vk.com API. Please read the full documentation before you start.

7.1. Authorization Code Flow for User

OAuth 2.0 Authorization Code Flow allows calling methods from the server side.

This flow includes two steps — obtaining an authorization code and exchanging the code for an access token. Primarily you should obtain the "code" (manual) and then use this method to complete the flow:

UserAuthResponseauthResponse = vk.oAuth()
.userAuthorizationCodeFlow(APP_ID, CLIENT_SECRET, REDIRECT_URI, code)
.execute();
UserActoractor = newUserActor(authResponse.getUserId(), authResponse.getAccessToken());

This takes your application ID, secure key, redirect URI, enumerated scopes and code obtained on the previous step of the flow.

When succeed, a UserActor object is created. You can call VK API methods on behalf of a user.

7.2. Authorization Code Flow for Community

The difference from the previous flow is that you send the groupId parameter to obtain the community's access token. Please read the full manual.

GroupAuthResponseauthResponse = vk.oAuth()
.groupAuthorizationCodeFlow(APP_ID, CLIENT_SECRET, REDIRECT_URI, code)
.execute();
GroupActoractor = newGroupActor(groupId, authResponse.getAccessTokens().get(groupId));

When succeed, a GroupActor object is created. You can call VK API methods on behalf of a community.

7.3. Handling need_validation error

Proceeding each of previous authorization flows you can receive a "need_validation" error. Use the following code to handle the error:

UserAuthResponseauthResponse;
try {
authResponse = vk.oAuth()
.userAuthorizationCodeFlow(APP_ID, CLIENT_SECRET, REDIRECT_URI, code)
.execute();
} catch (OAuthExceptione) {
e.getRedirectUri();
}
UserActoractor = newUserActor(authResponse.getUserId(), authResponse.getAccessToken());

7.4. Client Credentials Flow

This flow allows to interact with API service methods with "secure" prefix. Use this method:

ServiceClientCredentialsFlowResponseauthResponse = vk.oAuth()
.serviceClientCredentialsFlow(APP_ID, CLIENT_SECRET)
.execute();
ServiceActoractor = newServiceActor(APP_ID, authResponse.getAccessToken());

When succeed, a ServiceActor object is created. You can call VK API methods on behalf of an app.

8. API Requests

You can find the full list of VK API methods here.

Request sample

GetResponsegetResponse = vk.wall().get(actor)
.ownerId(1)
.count(100)
.offset(5)
.filter("owner")
.execute();

Request sample with common method parameters:

List<UserXtrCounters> users = vk.users().get(actor)
.userIds("1")
.fields(UserField.VERIFIED, UserField.SEX)
.lang(Lang.EN)
.execute();

The full list of common parameters is available on this page.

Request sample for uploading and posting photos on user wall.

PhotoUploadserverResponse = vk.photos().getWallUploadServer(actor).execute();
WallUploadResponseuploadResponse = vk.upload().photoWall(serverResponse.getUploadUrl(), file).execute();
List<Photo> photoList = vk.photos().saveWallPhoto(actor, uploadResponse.getPhoto())
.server(uploadResponse.getServer())
.hash(uploadResponse.getHash())
.execute();
Photophoto = photoList.get(0); StringattachId = "photo" + photo.getOwnerId() + "_" + photo.getId();
GetResponsegetResponse = vk.wall().post(actor)
.attachments(attachId)
.execute();

9. Execute requests

You can find more information about execute method here.

Code

JsonElementresponse = vk.execute().code(actor, "return API.wall.get({\"count\": 1})")
.execute();

Storage function

JsonElementresponse = vk.execute().storageFunction(actor, "foo")
.funcV(2) // set storage function version
.unsafeParam("user_id", 1) // set storage function argument
.execute();

Batch requests

JsonElementresponse = vk.execute().batch(actor,
vk.database().getChairs(1).count(10),
vk.database().getCities(1),
vk.groups().getMembers(actor).groupId(groupId)
).execute();

10. Error Handling

Common Example

try {
vk.wall().post(actor)
.message("Hello world")
.execute();
} catch (ApiWallLinksForbiddenExceptione) {
// Links posting is prohibited
} catch (ApiExceptione) {
// Business logic error
} catch (ClientExceptione) {
// Transport layer error
}

Captcha error handling

StringcaptchaSid = null;
StringcaptchaImg = null;
try {
vk.wall().post(actor).message("Hello world").execute();
} catch (ApiCaptchaExceptione) {
captchaSid = e.getCaptchaSid();
captchaImg = e.getCaptchaImg();
}
//Showing captcha image...if (captchaImg != null) {
vk.wall().post(actor)
.message("Hello world")
.captchaSid(captchaSid)
.captchaKey(captchaKey)
.execute();
}

11. Callback API handler

Override methods from CallbackApi class for handling events

publicclassCallbackApiHandlerextendsCallbackApi {
@OverridepublicvoidmessageNew(IntegergroupId, Messagemessage) {
System.out.println(message.getText());
}
}

12. Callback API Long Poll handler

Enable Callback API Long Poll for needed group and specify which events should be tracked

HttpTransportClienthttpClient = HttpTransportClient.getInstance();
VkApiClientvk = newVkApiClient(httpClient);
vk.groups().setLongPollSettings(groupActor).enabled(true)
.wallPostNew(true)
.messageNew(true)
.execute();

(WIP) Override methods from CallbackApiLongPoll class for handling events and create needed constructors

publicclassCallbackApiLongPollHandlerextendsCallbackApiLongPoll {
publicCallbackApiLongPollHandler(VkApiClientclient, UserActoractor, IntegergroupId) {
super(client, actor, groupId);
}
publicCallbackApiLongPollHandler(VkApiClientclient, GroupActoractor) {
super(client, actor);
}
@OverridepublicvoidmessageNew(IntegergroupId, Messagemessage) {
System.out.println("messageNew: " + message.toString());
}
@OverridepublicvoidwallPostNew(IntegergroupId, WallPostwallPost) {
System.out.println("wallPostNew: " + wallPost.toString());
}
}

In order to use the created CallbackApiLongPollHandler which overrides methods from CallBackApiLongPoll, the instance of it needs to be created and method run called

CallbackApiLongPollHandlerhandler = newCallbackApiLongPollHandler(vk, groupActor);
handler.run();

13. Streaming API

Initialization

//Init clientsTransportClienttransportClient = newHttpTransportClient();
VkApiClientvkClient = newVkApiClient(transportClient);
VkStreamingApiClientstreamingClient = newVkStreamingApiClient(transportClient);
//Create service actorIntegerappId = 4123123;
StringaccessToken = "sadf0asdf0asdfsadfassadf0asdf0asdfsadfassadf0asdf0asdfsadfas";
ServiceActoractor = newServiceActor(appId, accessToken);
//Get streaming actorGetServerUrlResponsegetServerUrlResponse = vkClient.streaming().getServerUrl(actor).execute();
StreamingActoractor = newStreamingActor(getServerUrlResponse.getEndpoint(), getServerUrlResponse.getKey());

Add rule

//Create ruleStringtag = "1";
Stringvalue = "ok";
StreamingResponseresponse = streamingClient.rules().add(actor, tag, value).execute();

Get rules

//Get rulesStreamingGetRulesResponseresponse = streamingClient.rules().get(actor).execute();

Delete rule

//Delete ruleStringtag = "1";
streamingClient.rules().delete(actor, tag).execute();

Stream handler

Implement handle method from StreamingEventHandler class for handling stream events

streamingClient.stream().get(actor, newStreamingEventHandler() {
@Overridepublicvoidhandle(StreamingCallbackMessagemessage) {
System.out.println(message);
}
}).execute();

14. Usage Example

As an SDK usage example we have released the YouTrack bot. The documentation can be found here.