One Man Studio

vBulletin version used in this tutorial: 5.1.4

If vBulletin.com don’t want to place documentation about their API, I will do it here.

Little about API is here: http://www.vbulletin.com/vbcms/content.php/334-mobile-api , this is about vB4 but pretty similiar to vB5.

Theory:

vB API uses GET calls to communicate with external application, so you better take care about SSL connection.

When using API you call certain methods that are spread in classes which you can find in directory /PathToYourVbulletin/core/vb/api/. Each file contains class with the same name and some methods which you can call. I couldn’t find documentation other than inline so I ran PHPDoc on vB source. You can see it here: vBulletin 5 API

To call certain method you have to name it in request. Because all vB API classes extends API main class vB_Api and name convention is that each API class name begins with “vB_Api_” (?!). After that comes class name related to class function. Call contains part of class name and method name separated with dot “.”, eg. “user.login“.

Method parameters can be passes in GET request. Simply parameters request have to be called exactly the same as in class method.

Better understanding of how vBulletin structure looks like and how does it work will certainly help you in finding right method that you actually require [@TODO Tutorial about how vB works].

Practice:

Initalization

First of all you have to initialize API. You do it by calling address like this:

http://yoursite.com/forum/api.php?
	api_m=api.init&
	clientname=client_name&
	clientversion=1.1&
	platformname=CMSx&
	platformversion=0.9&
	uniqueid=uniqueId

Only api_m parameter is mandatory. Rest of parameters is metadata about connection that is stored in database. Because you can have more than one application using the API, you might want to control them. All actions made by API are stored in the database, so you can track and eliminate eventual bad apples.

You can find init() method in api.php file.

In response you will receive few identifiers that you should store somewhere as they are required for any further call. They are:

• apiaccesstoken – this one you will need to send to authenticate the request
• apiclientid – this one you will need to send to authenticate the request
• secret – this one is needed only to generate signature

There is one more value that you will need to generate signature API key which you generate individually in admincp of your vBulletin instance.

Calling

After that you can start communicating with API. But one more thing. Each API call requires to send signature of this call, so vBulletin can verify that call wasn’t malformed. Signature is md5 shorcut of method name + method parameters + apiaccesstoken + apiclientid + secret + apikey. Here is example how code generating such signature would look like:

// Method name and its aruments
$request_params = [
	'api_m' => 'user.login', 
	'username' => 'username', 
	'password' => 'password'
]; 

// Sort them so they are in same order on client and server side
ksort($request_params); 

//Change parameters into string
$signstr = http_build_query($requestparams, '', '&'); 
// $signstr = 'api_m=user.login&password=password&username=username';

// Add rest and made md5 out of it signstr + accesstoken + clientid + secret + API key
$sig = md5($signstr . $apiaccesstoken . $apiclientid . $secret . $apikey);

Example request for User::login() method should look like this:

http://yoursite.com/forum/api.php?
	api_m=user.login&
	api_s=api_access_token&
	api_c=api_client_id&
	username=username&
	password=some_password&
	api_sig=api_signature

 Response

Response is either JSON string, vB page or JSON string with error messages.

Successful response varies for each method called. Usually it is  array of data where you have to find what interests you the most. Sometimes it is Boolean value if you just check access for example.

Debugging

Error response depends on state of forum. If it is in debug mode you might receive JSON with error message or HTML page with debug part. JSON error messages are very rare, mostly it is HTML document. Don’t know why exactly, you have to ask vB developers. Looks like JSON errors shows only when API call is sucessful and errors come form other reasons like incorrect password. When vB is in normal state, in case of error you will receive HTML document with message that request cannot be completed. So you might have troubles in debugging when you’re trying to call API on a live site. How to deal with it. You can have an if condition in your configuration file, like this:

if($_SERVER['REMOTE_ADDR'] == "127.0.0.1"){
	$config['debug'] = true;
}

You have to do it in two places to be sure that forum will be in debug state for your every call. There are two config.php files and I’m not sure if in every situation the same is used or the override each other. Again You have to ask vB developers. Here are locations of config.php files:

/PathToYourVbulletin/config.php
/PathToYourVbulletin/core/includes/config.php

With debug mode you can just var_dump() answer to see what happend.

Some examples

Here are some examples of functions that I had used.

User login

Api call: user.login

Parameters: 

• username – user login
• password(optional) – not really optional if you want to login, You cannot login without a password. I didn’t check what you can get with only username.
• md5password(optional) – md5 shortcut of password, never used it
• md5passwordutf(optional) – well its good that this is optional, because i have no idea what is it for
• logintype – looks like any value used by this parameter is “fbauto”, and it allows to login you through Facebook. But I don’t see how you can use it in API.

Result:

JSON with user data or JSON with errors.

Fetch(Get) User Data

Api call: user.fetchCurrentUserinfo

Parameters: 

• none

Result:

JSON Array with a lot of user data

Get Node (this could be Thread, Post or Private Message)

Api call: node.getNode

Parameters: 

• none

Result:

JSON Array with node data, most of it covers contents of table {prefix}_node

Coming soon.