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…
- Could be self hosted
- Developed in PHP for ease of customizing
- Was MIT licienced
- Had a good and commonly used JSON API with good examples that accepted POST
- 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.