Start to write the API documentation

1 files changed, 323 insertions, 0 deletions

diff --git a/docs/api-json-rpc.markdown b/docs/api-json-rpc.markdown
new file mode 100644
index 00000000..7b0b795c
--- /dev/null
+++ b/docs/api-json-rpc.markdown
@@ -0,0 +1,323 @@
+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**
+
+
+
+
+### 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**