Tutorial: Setting up and using API to batch create discussions

lkj897

I wanted to use the Vanilla API, but I'm not a programmer, and even though I read through the documentation many times and asked a couple of people, I didn't really get the help necessary to install and run this as a 'newbie.' So I spend two days fooling around and figured it out myself! I hope this tutorial helps you, but keep in mind it's supplied for educational purposes only, and I can't be held accountable for any of the information presented here or provide additional guidance. Good luck!

INSTALL VANILLA MASTER

Go to https://github.com/vanilla/vanilla and download ZIP. This is the 2.2 'master' version (if you download the stable release (2.1), API won't work.

Upload the ZIP to the desired location on your server, and extract.

SET UP YOUR DATABASE

Using something like MySQL Database WIzard in your host account's control panel, create a new database and make note of the username, password, etc.

On your browswer, go to the directory where you installed Vanilla (eg, http://mysite.com/vanilla-master/) [Note: If you get a blank page, it might be because your PHP version is lower than 5.3]

Enter the details of the database you just created. You will need the admin username and email later to create the token.

You should now be able to access the dashboard and your Vanilla forum.

INSTALL VANILLA API

Download ZIP of Kasper's API from https://github.com/kasperisager/vanilla-api

Upload to your vanilla/applications folder and extract.

Rename folder 'vanilla-api-master' to 'api'

Go to the Vanilla dashboard, find Addons on the sidebar, and click applications.

Enable Vanilla API. Click Settings and take note of the endpoint URL and the API Secret key.

CREATE A TOKEN SCRIPT FILE

On the Vanilla folder in your server, create a file called something like get-token.php

Put the following code in the file:

< ?php
$secret='the-key-from-API-settings';
$Request = array();
$Request['username'] = 'your-admin-name';
$Request['email'] = 'your-admin-email';
$Request['timestamp'] = 'unix-timestamp';
ksort($Request, SORT_STRING);
// Delimit the data values with a dash
$Request = implode('-', $Request);
$Token = hash_hmac('sha256', strtolower($Request), $secret);
echo $Token
? >

The secret, username and email parameters are self-explanatory (obtaining Secret is explained in the previous step).

For the unix-timestamp, go to a site like http://www.unixtimestamp.com/ and copy the timestamp. Paste in above where it says unix-timestamp. Save the file.

Now with your browser go to http://mysite.com/vanilla/get-token.php, and you should see a token. Copy it and use it in the next step.

Note: These tokens can only be used once per request, so for every request you will have to get a new timestamp, edit your get-token.php file, and refresh the get-token.php page to get a new token. There is a way to automate and pass keys without doing all of this, but that's beyond the scope of this tutorial. Also, once you are done you may want to delete the get-token.php file and not leave it around, since it contains your secret.

INSTALL POSTMAN

Using Chrome browser, go to the App store, and install the Postman - REST client. This is the app you will use to issue API requests.

You can download Kasper's API collection by clicking on Import Collection, and entering the URL https://www.getpostman.com/collections/88c667ea752bc4f0186e

You should now see a bunch of folders with APIs for Activities, Categories, etc.

You can run a test by going to the GET/configuration API. Enter the necessary information for the ULR params:

{{domain}} : your vanilla URL API endpoint, such as http://mysite.com/vanilla/
{{username}} : the admin user name you used to install Vanilla
{{email}} : the admin emai you used to install Vanilla
{{timestamp}} : the unix timestamp you generated and put in your get-token.php
{{token}} : the token generated through your get-token.php file

As far as Headers, remove the Accept and write Content-Type for Header, and application/json for value.

You should then be able to click Send and get the configuration results.

Similarly, you can now use any of the API by supplying the required info (remember to generate a new timestamp and token each time). Note that for some requests like POST/discussion you need to suply parameters (Name, Body, CategoryID) in the raw tab of presets (select JSON from the drop down menu).

USING POSTMAN TO RUN A COLLECTION WITH VARIABLES

I started all of this because I wanted to use the API to batch create a bunch of categories and discussions without having to do it manually one by one. Postman allows you to do this through the Collection Runner ($10 to add to your client!).

Basically, in the raw tab you would enter something with variables like this:

{
"Name": "{{discussion-name}}",
"Body": "{{discussion-body}}",
"CategoryID": 1
}

Then you need to create a csv file with the following strucutre:

discussion-name,discussion-body
Discussion1,Welcome
Discussion2,Welcome
etc

(Note: When I created this in Excel, it didn't like the format of the line endins, so I had to change the line endings from Mac to Unix by re-saving it in TextWrangler)

You then go to the Collection Runner, select the collection you want to run (you may want to create a new folder with just your copy of the POST/Discussion API), enter the iterations (number of lines or requests in your csv file), select the csv file, and click Start. Voila!

peregrine

thx. for the tutorial.

hgtonight

If you are looking to pre-populate the database with discussions based on a CSV file, I would have parsed it into SQL. Save you $10 at least.

Also, for purely random dummy data, I like the plugin @R_J made: http://vanillaforums.org/discussion/26297/dummy-data-for-vanilla-2-1b2

Pretty good tutorial

lkj897

Edit: You don't have to generate a token for every request. They are valid for about 5 minutes. To extend that, you can edit conf/config.php:

$Configuration['API']['Expiration'] = strtotime('5 minutes', 0);

phreak

@lkj897: Late, but still: Thanx for this introduction!

marvMartian

WARNING: TUTORIAL IS INCORRECT. You must supply both a Content-Type and an Accept header in order to get api to work. Both can be set to "application/json".

jack_joe

I am using curl, I am getting error

<?php $data = array( "Name" => "Test", "Body" => "Test New Testseries 2018", "CategoryID" => "65", "username" => "root", "email" => "root@example.com", "timestamp" => time() ); ksort($data, SORT_STRING); $signature = hash_hmac("sha256", strtolower(implode("-", $data)), "a2fde66c-0ffe-4024-ad89-0f443db2694f"); $data['token'] = $signature; $data_string = json_encode($data,true); $ch = curl_init('http://xyv.example.com/api/discussions'); curl_setopt($ch, CURLOPT_POST, 1); //curl_setopt($ch, CURLOPT_COOKIE, $_SERVER["HTTP_COOKIE"]); curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/json', 'Content-Length: ' . strlen($data_string)), "Accept: application/json" ); curl_setopt($ch, CURLOPT_HEADER, 1); curl_setopt($ch, CURLINFO_HEADER_OUT, true); $result = curl_exec($ch); curl_close($ch); print_r($result); echo json_decode($result,true); //echo $httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE); //echo $contenttype = curl_getinfo($ch, CURLINFO_CONTENT_TYPE); ?>

I have used latest release 0.5.0 vanilla api

jack_joe

I am getting this error: { "Code": 400, "Exception": "Unsupported content type: /" }

lgeorge

im trying to authenticate in postman with a local setup

im getting the key like that, with the secret form the user, from the backend

$secret='va.GFcF4-fvhIcW-jx3bK_JEAQ2G10VvHEo.wt-LcA.JvYkORe';

$Request = array();

$Request['username'] = 'root';

$Request['email'] = 'gliatopoulos@cognity.gr';

//$Request['timestamp'] = '1572512993';

$Request['timestamp']=time();

echo $Request['timestamp']."<br>";

ksort($Request, SORT_STRING);

// Delimit the data values with a dash

$Request = implode('-', $Request);

$Token = hash_hmac('sha256', strtolower($Request), $secret);

echo $Token;

im getting the token and sending this from postman

http://localhost/vf/index.php?p=/api/v2/users&timestamp=1572596537&token=0210e0fc229d95c8dab9876997e7a3c954a323463483ef57f040406d6b4abc89

the result is

{

"message": "You need one of Garden.Users.Add, Garden.Users.Edit, Garden.Users.Delete permissions to do that.",

"status": 403,

"permissions": [

"Garden.Users.Add",

"Garden.Users.Edit",

"Garden.Users.Delete"

],

"description": null

}