YunoHost-Apps/kanboard_ynh
1
0
Fork 0
mirror of https://github.com/YunoHost-Apps/kanboard_ynh.git synced 2024-09-03 19:36:17 +02:00
Code Issues Activity Actions
kanboard_ynh/sources/docs/api-json-rpc.markdown
mbugeia 5e51bcd6e9 Init files + sources 
Kanboard 1.0.6
2014-07-20 12:26:15 +02:00

396 lines
10 KiB
Markdown
Raw Blame History

Json-RPC API
============
Protocol
--------
Kanboard use the protocol Json-RPC to interact with external programs.
JSON-RPC is a remote procedure call protocol encoded in JSON.
Almost the same thing as XML-RPC but with the JSON format.
We use the [version 2 of the protocol](http://www.jsonrpc.org/specification).
You must call the API with a `POST` HTTP request.
Credentials
-----------
The API credentials are available on the settings page.
- API end-point: `http://YOUR_SERVER/jsonrpc.php`
- Username: `jsonrpc`
- Password: Random token (API token on the settings page)
The API use the [HTTP Basic Authentication Scheme described in the RFC2617](http://www.ietf.org/rfc/rfc2617.txt).
If there is an authentication error, you got an HTTP status code `401 Not Authorized`.
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 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
)
)
```
Procedures
----------
### createProject
- Purpose: **Create a new project**
- Parameters: **name** (string)
- Result on success: **true**
- Result on failure: **false**
### getProjectById
- Purpose: **Get project information**
- Parameters: **project_id** (integer)
- Result on success: **project properties**
- Result on failure: **null**
### getProjectByName
- Purpose: **Get project information**
- Parameters: **name** (string)
- Result on success: **project properties**
- Result on failure: **null**
### getAllProjects
- Purpose: **Get all available projects**
- Parameters: **none**
- Result on success: **List of projects**
- Result on failure: **false**
### updateProject
- Purpose: **Update a project**
- Parameters: Key/value pair composed of the **id** (integer), **name** (string), **is_active** (integer, optional)
- Result on success: **true**
- Result on failure: **false**
### removeProject
- Purpose: **Remove a project**
- Parameters: **project_id** (integer)
- Result on success: **true**
- Result on failure: **false**
### getBoard
- Purpose: **Get all necessary information to display a board**
- Parameters: **project_id** (integer)
- Result on success: **board properties**
- Result on failure: **null**
### getColumns
- Purpose: **Get all columns information for a given project**
- Parameters: **project_id** (integer)
- Result on success: **columns properties**
- Result on failure: **null**
### moveColumnUp
- Purpose: **Move up the column position**
- Parameters: **project_id** (integer), **column_id** (integer)
- Result on success: **true**
- Result on failure: **false**
### moveColumnDown
- Purpose: **Move down the column position**
- Parameters: **project_id** (integer), **column_id** (integer)
- Result on success: **true**
- Result on failure: **false**
### updateColumn
- Purpose: **Update column properties**
- Parameters: **column_id** (integer), **values** (**title** string, **task_limit** integer)
- Result on success: **true**
- Result on failure: **false**
### addColumn
- Purpose: **Add a new column**
- Parameters: **project_id** (integer), **values** (**title** string, **task_limit** integer)
- Result on success: **true**
- Result on failure: **false**
### removeColumn
- Purpose: **Remove a column**
- Parameters: **column_id** (integer)
- Result on success: **true**
- Result on failure: **false**
### getAllowedUsers
- Purpose: **Get allowed users for a given project**
- Parameters: **project_id** (integer)
- Result on success: Key/value pair of user_id and username
- Result on failure: **false**
### revokeUser
- Purpose: **Revoke user access for a given project**
- Parameters: **project_id** (integer), **user_id** (integer)
- Result on success: **true**
- Result on failure: **false**
### allowUser
- Purpose: **Grant user access for a given project**
- Parameters: **project_id** (integer), **user_id** (integer)
- Result on success: **true**
- Result on failure: **false**
### createTask
- Purpose: **Create a new task**
- Parameters: Key/value pair composed of the **title** (string), **description** (string, optional), **color_id** (string), **project_id** (integer), **column_id** (integer), **owner_id** (integer, optional), **score** (integer, optional), **date_due** (integer, optional), **category_id** (integer, optional)
- Result on success: **true**
- Result on failure: **false**
### getTask
- Purpose: **Get task information**
- Parameters: **task_id** (integer)
- Result on success: **task properties**
- Result on failure: **null**
### getAllTasks
- Purpose: **Get all available tasks**
- Parameters: **project_id** (integer)
- Result on success: **List of tasks**
- Result on failure: **false**
### updateTask
- Purpose: **Update a task**
- Parameters: Key/value pair composed of the **id** (integer), **title** (string), **description** (string, optional), **color_id** (string), **project_id** (integer), **column_id** (integer), **owner_id** (integer, optional), **score** (integer, optional), **date_due** (integer, optional), **category_id** (integer, optional)
- Result on success: **true**
- Result on failure: **false**
### removeTask
- Purpose: **Remove a task**
- Parameters: **task_id** (integer)
- Result on success: **true**
- Result on failure: **false**
### createUser
- Purpose: **Create a new user**
- Parameters: Key/value pair composed of the **username** (string), **password** (string), **confirmation** (string), **name** (string, optional), **email** (string, optional), is_admin (integer, optional), **default_project_id** (integer, optional)
- Result on success: **true**
- Result on failure: **false**
### getUser
- Purpose: **Get user information**
- Parameters: **user_id** (integer)
- Result on success: **user properties**
- Result on failure: **null**
### getAllUsers
- Purpose: **Get all available users**
- Parameters: **none**
- Result on success: **List of users**
- Result on failure: **false**
### updateUser
- Purpose: **Update a user**
- Parameters: Key/value pair composed of the **id** (integer), **username** (string), **password** (string), **confirmation** (string), **name** (string, optional), **email** (string, optional), is_admin (integer, optional), **default_project_id** (integer, optional)
- Result on success: **true**
- Result on failure: **false**
### removeUser
- Purpose: **Remove a user**
- Parameters: **user_id** (integer)
- Result on success: **true**
- Result on failure: **false**
### createCategory
- Purpose: **Create a new category**
- Parameters: Key/value pair composed of the **name** (string), **project_id** (integer)
- Result on success: **true**
- Result on failure: **false**
### getCategory
- Purpose: **Get category information**
- Parameters: **category_id** (integer)
- Result on success: **category properties**
- Result on failure: **null**
### getAllCategories
- Purpose: **Get all available categories**
- Parameters: **project_id** (integer)
- Result on success: **List of categories**
- Result on failure: **false**
### updateCategory
- Purpose: **Update a category**
- Parameters: Key/value pair composed of the **id** (integer), **name** (string), **project_id** (integer)
- Result on success: **true**
- Result on failure: **false**
### removeCategory
- Purpose: **Remove a category**
- Parameters: **category_id** (integer)
- Result on success: **true**
- Result on failure: **false**
### createComment
- Purpose: **Create a new comment**
- Parameters: Key/value pair composed of the **task_id** (integer), **user_id** (integer), **comment** (string)
- Result on success: **true**
- Result on failure: **false**
### getComment
- Purpose: **Get comment information**
- Parameters: **comment_id** (integer)
- Result on success: **comment properties**
- Result on failure: **null**
### getAllComments
- Purpose: **Get all available comments**
- Parameters: **none**
- Result on success: **List of comments**
- Result on failure: **false**
### updateComment
- Purpose: **Update a comment**
- Parameters: Key/value pair composed of the **id** (integer), **task_id** (integer), **user_id** (integer), **comment** (string)
- Result on success: **true**
- Result on failure: **false**
### removeComment
- Purpose: **Remove a comment**
- Parameters: **comment_id** (integer)
- Result on success: **true**
- Result on failure: **false**
### createSubtask
- Purpose: **Create a new subtask**
- Parameters: Key/value pair composed of the **title** (integer), time_estimated (int, optional), task_id (int), user_id (int, optional)
- Result on success: **true**
- Result on failure: **false**
### getSubtask
- Purpose: **Get subtask information**
- Parameters: **subtask_id** (integer)
- Result on success: **subtask properties**
- Result on failure: **null**
### getAllSubtasks
- Purpose: **Get all available subtasks**
- Parameters: **none**
- Result on success: **List of subtasks**
- Result on failure: **false**
### updateSubtask
- Purpose: **Update a subtask**
- Parameters: Key/value pair composed of the **id** (integer), **title** (integer), status (integer, optional) time_estimated (int, optional), time_spent (int, optional), task_id (int), user_id (int, optional)
- Result on success: **true**
- Result on failure: **false**
### removeSubtask
- Purpose: **Remove a subtask**
- Parameters: **subtask_id** (integer)
- Result on success: **true**
- Result on failure: **false**
Reference in a new issue View git blame Copy permalink