From e9fedf3e5cd63aea4da7a71f6647ee427c62fa49 Mon Sep 17 00:00:00 2001 From: Frederic Guillot Date: Sat, 5 Dec 2015 20:31:27 -0500 Subject: Rewrite of the authentication and authorization system --- doc/api-examples.markdown | 184 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 184 insertions(+) create mode 100644 doc/api-examples.markdown (limited to 'doc/api-examples.markdown') diff --git a/doc/api-examples.markdown b/doc/api-examples.markdown new file mode 100644 index 00000000..9b1ed12a --- /dev/null +++ b/doc/api-examples.markdown @@ -0,0 +1,184 @@ +API Examples +============ + +Example with cURL +----------------- + +From the command line: + +```bash +curl \ +-u "jsonrpc:19ffd9709d03ce50675c3a43d1c49c1ac207f4bc45f06c5b2701fbdf8929" \ +-d '{"jsonrpc": "2.0", "method": "getAllProjects", "id": 1}' \ +http://localhost/kanboard/jsonrpc.php +``` + +Response from the server: + +```json +{ + "jsonrpc":"2.0", + "id":1, + "result":[ + { + "id":"1", + "name":"API test", + "is_active":"1", + "token":"6bd0932fe7f4b5e6e4bc3c72800bfdef36a2c5de2f38f756dfb5bd632ebf", + "last_modified":"1403392631" + } + ] +} +``` + +Example with Python +------------------- + +Here a basic example written in Python to create a task: + +```python +#!/usr/bin/env python + +import requests +import json + +def main(): + url = "http://demo.kanboard.net/jsonrpc.php" + api_key = "be4271664ca8169d32af49d8e1ec854edb0290bc3588a2e356275eab9505" + headers = {"content-type": "application/json"} + + payload = { + "method": "createTask", + "params": { + "title": "Python API test", + "project_id": 1 + }, + "jsonrpc": "2.0", + "id": 1, + } + + response = requests.post( + url, + data=json.dumps(payload), + headers=headers, + auth=("jsonrpc", api_key) + ) + + if response.status_code == 401: + print "Authentication failed" + else: + result = response.json() + + assert result["result"] == True + assert result["jsonrpc"] + assert result["id"] == 1 + + print "Task created successfully!" + +if __name__ == "__main__": + main() +``` + +Run this script from your terminal: + +```bash +python jsonrpc.py +Task created successfully! +``` + +Example with a PHP client +------------------------- + +I wrote a simple [Json-RPC Client/Server library in PHP](https://github.com/fguillot/JsonRPC), here an example: + +```php +authentication('jsonrpc', '19ffd9709d03ce50675c3a43d1c49c1ac207f4bc45f06c5b2701fbdf8929'); + +print_r($client->getAllProjects()); + +``` + +The response: + +``` +Array +( + [0] => Array + ( + [id] => 1 + [name] => API test + [is_active] => 1 + [token] => 6bd0932fe7f4b5e6e4bc3c72800bfdef36a2c5de2f38f756dfb5bd632ebf + [last_modified] => 1403392631 + ) + +) +``` + +Example with Ruby +----------------- + +This example can be used with Kanboard configured with Reverse-Proxy authentication and the API configured with a custom authentication header: + +```ruby +require 'faraday' + +conn = Faraday.new(:url => 'https://kanboard.example.com') do |faraday| + faraday.response :logger + faraday.headers['X-API-Auth'] = 'XXX' # base64_encode('jsonrpc:API_KEY') + faraday.basic_auth(ENV['user'], ENV['pw']) # user/pass to get through basic auth + faraday.adapter Faraday.default_adapter # make requests with Net::HTTP +end + +response = conn.post do |req| + req.url '/jsonrpc.php' + req.headers['Content-Type'] = 'application/json' + req.body = '{ "jsonrpc": "2.0", "id": 1, "method": "getAllProjects" }' +end + +puts response.body +``` + + +Example with Java +----------------- + +This is a basic example using Spring. For proper usage see [this link](http://spring.io/guides/gs/consuming-rest). + +```java +import java.io.UnsupportedEncodingException; +import java.util.Base64; + +import org.springframework.http.HttpEntity; +import org.springframework.http.HttpHeaders; +import org.springframework.http.MediaType; +import org.springframework.web.client.RestTemplate; + +public class ProjectService { + + public void getAllProjects() throws UnsupportedEncodingException { + + RestTemplate restTemplate = new RestTemplate(); + + String url = "http://localhost/kanboard/jsonrpc.php"; + String requestJson = "{\"jsonrpc\": \"2.0\", \"method\": \"getAllProjects\", \"id\": 1}"; + String user = "jsonrpc"; + String apiToken = "19ffd9709d03ce50675c3a43d1c49c1ac207f4bc45f06c5b2701fbdf8929"; + + // encode api token + byte[] xApiAuthTokenBytes = String.join(":", user, apiToken).getBytes("utf-8"); + String xApiAuthToken = Base64.getEncoder().encodeToString(xApiAuthTokenBytes); + + // consume request + HttpHeaders headers = new HttpHeaders(); + headers.add("X-API-Auth", xApiAuthToken); + headers.setContentType(MediaType.APPLICATION_JSON); + HttpEntity entity = new HttpEntity(requestJson, headers); + String answer = restTemplate.postForObject(url, entity, String.class); + System.out.println(answer); + } +} +``` -- cgit v1.2.3 From 94207cf8ea41132fd7279ab08845677542eb3c9f Mon Sep 17 00:00:00 2001 From: Frederic Guillot Date: Sat, 23 Jan 2016 10:52:55 -0500 Subject: Update doc and readme --- README.md | 41 +++++++++++----------------------- doc/api-examples.markdown | 56 ++++++++++------------------------------------- doc/faq.markdown | 34 ++++++++++++++-------------- 3 files changed, 41 insertions(+), 90 deletions(-) (limited to 'doc/api-examples.markdown') diff --git a/README.md b/README.md index 61730b77..ebfdc767 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Kanboard [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/fguillot/kanboard/badges/quality-score.png?s=2b6490781608657cc8c43d02285bfafb4f489528)](https://scrutinizer-ci.com/g/fguillot/kanboard/) [![SensioLabsInsight](https://insight.sensiolabs.com/projects/5e50750e-fc62-4a1f-b02a-71991123a2a7/mini.png)](https://insight.sensiolabs.com/projects/5e50750e-fc62-4a1f-b02a-71991123a2a7) -Kanboard is a project management software that uses the Kanban methodology. +Kanboard is a project management software that focus on the Kanban methodology. Official website: @@ -13,38 +13,23 @@ Official website: - Multiple boards with the ability to drag and drop tasks - Open source and self-hosted - Super simple installation -- Translated in 24 languages -- Distributed under [MIT License](LICENSE) -- [List of features are available on the website](http://kanboard.net/features) -- [Change Log](ChangeLog) +- Translated in many languages +- Distributed under [MIT License](https://github.com/fguillot/kanboard/blob/master/LICENSE) +- The complete [list of features are available on the website](http://kanboard.net/features) +- [Change Log](https://github.com/fguillot/kanboard/blob/master/ChangeLog) +- [Documentation](https://github.com/fguillot/kanboard/blob/master/doc/index.markdown) [![Deploy](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy) -Known bugs and feature requests -------------------------------- - -- Bug tracker: - Authors ------- -- Main developer: Frédéric Guillot (fguillot) -- [List of contributors](CONTRIBUTORS.md) - -Documentation -------------- - -- [Read the documentation](doc/index.markdown) - -Related projects ----------------- +- Main developer: [Frédéric Guillot](https://github.com/fguillot) +- [List of contributors](https://github.com/fguillot/kanboard/blob/master/CONTRIBUTORS.md) -List of plugins: http://kanboard.net/plugins +Installation and Upgrade +------------------------ -- [Kanboard API python client by @freekoder](https://github.com/freekoder/kanboard-py) -- [Kanboard Presenter by David Eberlein](https://github.com/davideberlein/kanboard-presenter) -- [CSV2Kanboard by @ashbike](https://github.com/ashbike/csv2kanboard) -- [Kanboard for Yunohost by @mbugeia](https://github.com/mbugeia/kanboard_ynh) -- [Trello import script by @matueranet](https://github.com/matueranet/kanboard-import-trello) -- [Chrome extension by Timo](https://chrome.google.com/webstore/detail/kanboard-quickmenu/akjbeplnnihghabpgcfmfhfmifjljneh?utm_source=chrome-ntp-icon), [Source code](https://github.com/BlueTeck/kanboard_chrome_extension) -- [Python client script by @dzudek](https://gist.github.com/fguillot/84c70d4928eb1e0cb374) +- [Requirements](http://kanboard.net/documentation/requirements) +- [Installation instructions](http://kanboard.net/documentation/installation) +- [Upgrade to a new version](http://kanboard.net/documentation/update) diff --git a/doc/api-examples.markdown b/doc/api-examples.markdown index 9b1ed12a..14d5db98 100644 --- a/doc/api-examples.markdown +++ b/doc/api-examples.markdown @@ -34,62 +34,30 @@ Response from the server: Example with Python ------------------- -Here a basic example written in Python to create a task: +You can use the [official Python client for Kanboard](https://github.com/kanboard/kanboard-api-python): -```python -#!/usr/bin/env python - -import requests -import json - -def main(): - url = "http://demo.kanboard.net/jsonrpc.php" - api_key = "be4271664ca8169d32af49d8e1ec854edb0290bc3588a2e356275eab9505" - headers = {"content-type": "application/json"} - - payload = { - "method": "createTask", - "params": { - "title": "Python API test", - "project_id": 1 - }, - "jsonrpc": "2.0", - "id": 1, - } +```bash +pip install kanboard +``` - response = requests.post( - url, - data=json.dumps(payload), - headers=headers, - auth=("jsonrpc", api_key) - ) +Here an example to create a project and a task: - if response.status_code == 401: - print "Authentication failed" - else: - result = response.json() +```python +from kanboard import Kanboard - assert result["result"] == True - assert result["jsonrpc"] - assert result["id"] == 1 +kb = Kanboard("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token") - print "Task created successfully!" +project_id = kb.create_project(name="My project") -if __name__ == "__main__": - main() +task_id = kb.create_task(project_id=project_id, title="My task title") ``` -Run this script from your terminal: - -```bash -python jsonrpc.py -Task created successfully! -``` +There are more examples on the [official website](https://github.com/kanboard/kanboard-api-python). Example with a PHP client ------------------------- -I wrote a simple [Json-RPC Client/Server library in PHP](https://github.com/fguillot/JsonRPC), here an example: +You can use this [Json-RPC Client/Server library for PHP](https://github.com/fguillot/JsonRPC), here an example: ```php - - How to install Kanboard on Yunohost? ------------------------------------ @@ -107,6 +93,18 @@ How to install Kanboard on Yunohost? There is a [package to install Kanboard on Yunohost easily](https://github.com/mbugeia/kanboard_ynh). +Where can I find a list of related projects? +-------------------------------------------- + +- [Kanboard API python client by @freekoder](https://github.com/freekoder/kanboard-py) +- [Kanboard Presenter by David Eberlein](https://github.com/davideberlein/kanboard-presenter) +- [CSV2Kanboard by @ashbike](https://github.com/ashbike/csv2kanboard) +- [Kanboard for Yunohost by @mbugeia](https://github.com/mbugeia/kanboard_ynh) +- [Trello import script by @matueranet](https://github.com/matueranet/kanboard-import-trello) +- [Chrome extension by Timo](https://chrome.google.com/webstore/detail/kanboard-quickmenu/akjbeplnnihghabpgcfmfhfmifjljneh?utm_source=chrome-ntp-icon), [Source code](https://github.com/BlueTeck/kanboard_chrome_extension) +- [Python client script by @dzudek](https://gist.github.com/fguillot/84c70d4928eb1e0cb374) + + Are there some tutorials about Kanboard in other languages? ----------------------------------------------------------- -- cgit v1.2.3