diff options
author | Frederic Guillot <fred@kanboard.net> | 2015-12-05 20:31:27 -0500 |
---|---|---|
committer | Frederic Guillot <fred@kanboard.net> | 2015-12-05 20:31:27 -0500 |
commit | e9fedf3e5cd63aea4da7a71f6647ee427c62fa49 (patch) | |
tree | abc2de5aebace4a2d7c94805552264dab6b10bc7 /doc/api-examples.markdown | |
parent | 346b8312e5ac877ce3192c2db3a26b500018bbb5 (diff) |
Rewrite of the authentication and authorization system
Diffstat (limited to 'doc/api-examples.markdown')
-rw-r--r-- | doc/api-examples.markdown | 184 |
1 files changed, 184 insertions, 0 deletions
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 +<?php + +$client = new JsonRPC\Client('http://localhost:8000/jsonrpc.php'); +$client->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<String> entity = new HttpEntity<String>(requestJson, headers); + String answer = restTemplate.postForObject(url, entity, String.class); + System.out.println(answer); + } +} +``` |