LiveCode to Kanboard API – Part 1

  1. Home / Uncategorized / LiveCode to Kanboard API – Part 1

LiveCode to Kanboard API – Part 1

Introduction

 

This is a two part tutorial for accessing the Kanbaord API via LiveCode.

Part 1 covers installation of Kanboard, introduces the processes involved and includes a fully worked LiveCode example for a basic request.

Part 2 will explore more complex requests and how to deal with the resulting json returned.

 

Part 1

 

Up until recently I’ve been using the Trello kanban for my workflow planning and tasks management. Trello is great but It’s proprietary software and I wanted a solution that…

  1. Could be self hosted
  2. Developed in PHP for ease of customizing
  3. Was MIT licienced
  4. Had a good and commonly used JSON API with good examples that accepted POST
  5. Could be accessed via LiveCode using POST

I settled on the excellent Kanboard developed by Frédéric Guillot which ticked all the boxes and also had a great plugins architecture.

Want to try a demo? https://www.softaculous.com/softaculous/demos/Kanboard

 

KanBoard

 

Installing Kanboard via Cpanel & Softaculous 

Many hosting providers (including LiveCode) provide Kanboard via their CP and the Softaculous software installer.

In Cpanel find the Softaculos Apps Installer section and scroll the Catergories to select Project Management.

Scroll down the list until the KB Kanboard section and click on the Kanboard heading.

Click on Install.

Fill out the installation details, enter your email address and click on the Install button.

Alternative install methods documentation can be found here:
https://kanboard.net/documentation/installation

 

Configuring Kanboard 

Login to your Kanboard, click on the top right down arrow and select Settings from the menu.

 

Click API from the left column and copy the API token and API endpoint details, these will be needed for the LiveCode script.

 

Add a test project to Kanboard

Open the Settings menu again and select Projects management.

 

Click on New project and enter any name for your project and click Save.

   

Each project you create is given a number which is the projects id. Your test project will be id=1

 

The Kanboard API

 

Kanboard and JSON-RPC both provide excellent documentaion, so rather than trying to relay this, please see the links below.

Please read the Kanboard API documentation first to familiarize yourself with its requirements:
https://kanboard.net/documentation/api-json-rpc

More deatiled information on JSON-RPC can be found here:
http://www.jsonrpc.org/specification

 

LiveCode

We will be using the Default method (HTTP(S) Basic) to access the API

This uses the Application API credentials (Username:jsonrpc, API token and API endpoint) which we noted earlier.

Username: jsonrpc
Password: API token on the settings page

We will POST header (-H) and data (-d) mimicking the curl example below which will return a list of all Kanboard projects.

curl \
-H ‘X-API-Auth: anNvbnJwYzoxOWZmZDk3MDlkMDNjZTUwNjc1YzNhNDNkMWM0OWMxYWMyMDdmNGJjNDVmMDZjNWIyNzAxZmJkZjg5Mjk=’ \
-d ‘{“jsonrpc”: “2.0”, “method”: “getAllProjects”, “id”: 1}’ \
http://localhost/kanboard/jsonrpc.php

Replace ???? in the example below with your details.

First we need to set the POST Address, this is the API end point.

put “https://???????????/kanboard/jsonrpc.php” into tEndPoint

 

We combine the User Credentials a into a clear text string.

put “jsonrpc” into tUserName
put “????????????????????????????????????” into tPassWordOrToken –API Token
put tUserName & “:” & tPassWordOrToken into tClearCredentials

 

Next we need to create the HTTP Headers so that JSON-RPC knows what it being sent and in what format.

put “Content-Type: application/json” & ” /” & CR into tHeaders

 

JSON-RPC needs to know that the Credentials string will be Base 64 encoded.

put base64Encode(tClearCredentials) into tEncodedCredentials

 

The resulting Base64 string may have a carriage return which needs to be removed.

replace cr with “” in tEncodedCredentials

 

Finally for the headers we set the Authorization type, append the previous header info and set the httpHeaders property to the headers string.

put “Authorization: Basic” && tEncodedCredentials after tHeaders

 

Next we build the json request object (the data).

Excerpt from the JSON-RPC 2.0 Specification

A rpc call is represented by sending a Request object to a Server. The Request object has the following members:
jsonrpc
A String specifying the version of the JSON-RPC protocol. MUST be exactly “2.0”.
method
A String containing the name of the method to be invoked. Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46) are reserved for rpc-internal methods and extensions and MUST NOT be used for anything else.
params
A Structured value that holds the parameter values to be used during the invocation of the method. This member MAY be omitted.
id
An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification.

This example does not require the params member and uses the getAllProjects call for the method.

put quote & “jsonrpc” & quote & “: “ & quote & “2.0” & quote into tJasonrpc –all data posts MUST start with this
put quote & “method” & quote & “: “ & quote & “getAllProjects” & quote into tMethod
put quote & “id” & quote & “: “ & quote & “1” & quote into tId

 

We format the data into a json data string.

put “{“ & tJasonrpc & “, “ & CRLF & tMethod & “, “ & CRLF & tId & “}” into tDataString

 

The json data is be previewed in an Answer dialog. We can elect to Cancel and clear the httpHeaders and data or post the json data to the end point, again clearing the headers after posting. The response from the API will be contained in the special local variable it.

Answer tDataString with “Cancel” or “OK”
if it is “Cancel” then
set the httpHeaders to empty
put empty into tDataString
exit mouseUp
else
post tDataString to url tEndPoint
put it
set the httpHeaders to empty
end if

A successful response from the API will be (if all has been correctly configured) similar to below:
Some sections redacted.

{“jsonrpc”:”2.0″,”result”:[{“id”:”1″,”name”:”KanBoard”,”is_active”:”1″,”token”:””,”last_modified”:”1509659555″,”is_public”:”0″,”is_private”:”0″,”is_everybody_allowed”:”0″,”description”:null,”identifier”:””,”start_date”:””,”end_date”:””,”owner_id”:”1″,”priority_default”:”0″,”priority_start”:”0″,”priority_end”:”3″,”email”:null,”predefined_email_subjects”:null,”url”:{“board”:”https:\/\/REDACTED\/kanboard\/?controller=BoardViewController&action=show&project_id=1″,”list”:”https:\/\/REDACTED\/kanboard\/?controller=TaskListController&action=show&project_id=1″}},{“id”:”1″,”name”:”REDACTED”,”is_active”:”1″,”token”:””,”last_modified”:”1509633035″,”is_public”:”0″,”is_private”:”0″,”is_everybody_allowed”:”0″,”description”:”REDACTED email alerts”,”identifier”:”REDACTED”,”start_date”:””,”end_date”:””,”owner_id”:”1″,”priority_default”:”0″,”priority_start”:”0″,”priority_end”:”3″,”email”:”REDACTED”,”predefined_email_subjects”:”New Task Added to REDACTED\r\n”,”url”:{“board”:”https:\/\/REDACTED\/kanboard\/?controller=BoardViewController&action=show&project_id=1″,”list”:”https:\/\/REDACTED\/kanboard\/?controller=TaskListController&action=show&project_id=1″}}],”id”:”1″}

Error Codes — just in case

code message meaning
-32700 Parse error Invalid JSON was received by the server.
An error occurred on the server while parsing the JSON text.
-32600 Invalid Request The JSON sent is not a valid Request object.
-32601 Method not found The method does not exist / is not available.
-32602 Invalid params Invalid method parameter(s).
-32603 Internal error Internal JSON-RPC error.
-32000 to -32099 Server error Reserved for implementation-defined server-errors.

 

The full LiveCode script

on mouseUp
–define API end point – should be https
put “https://???????????/kanboard/jsonrpc.php” into tEndPoint
–define user credentials
—   ????? relpace with your API details
put “jsonrpc” into tUserName
put “????????????????????????????????????” into tPassWordOrToken –API Token
put tUserName & “:” & tPassWordOrToken into tClearCredentials
–create headers
put “Content-Type: application/json” & ” /” & CR into tHeaders
put base64Encode(tClearCredentials) into tEncodedCredentials
–clean encoded credentials
replace cr with “” in tEncodedCredentials
–define authorization type and append user credentials
put “Authorization: Basic” && tEncodedCredentials after tHeaders
set the httpHeaders to tHeaders
–create data string
put quote & “jsonrpc” & quote & “: “ & quote & “2.0” & quote into tJasonrpc –all data posts MUST start with this
put quote & “method” & quote & “: “ & quote & “getAllProjects” & quote into tMethod
put quote & “id” & quote & “: “ & quote & “1” & quote into tId
–format data string to jason
put “{“ & tJasonrpc & “, “ & CRLF & tMethod & “, “ & CRLF & tId & “}” into tDataString
–preview post data string
Answer tDataString with “Cancel” or “OK”
if it is “Cancel” then
–clear headers and data
set the httpHeaders to empty
put empty into tDataString
exit mouseUp
else
–Post command
post tDataString to url tEndPoint
put it –send response to message box
set the httpHeaders to empty
end if
end mouseUp

 

This script has also been posted to LiveCode Share

http://livecodeshare.runrev.com/stack/849/LiveCode-to-Kanboard-API-Tutorial-Part-1

 

Part 2 will will deal with posting parameter arrays and how to deal with the resulting json.

 

End of part 1.