Merge branch 'master' of https://github.com/fguillot/kanboard

6 files changed, 89 insertions, 72 deletions

diff --git a/doc/api-authentication.markdown b/doc/api-authentication.markdown
index 962e5b1b..3ba1e8f5 100644
--- a/doc/api-authentication.markdown
+++ b/doc/api-authentication.markdown
@@ -1,48 +1,26 @@
 API Authentication
 ==================
 
-Default method (HTTP Basic)
----------------------------
+API endpoint
+------------
+
+URL: `https://YOUR_SERVER/jsonrpc.php`
 
-The API credentials are available on the settings page.
 
-- API end-point: `https://YOUR_SERVER/jsonrpc.php`
+Default method (HTTP Basic)
+---------------------------
 
-If you want to use the "application api":
+### Application credentials
 
 - Username: `jsonrpc`
 - Password: API token on the settings page
 
-Otherwise for the "user api", just use the real username/passsword.
+### User credentials
+
+- Use the real username and password
 
 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 will receive the HTTP status code `401 Not Authorized`.
-
-### Authorized User API procedures
-
-- getMe
-- getMyDashboard
-- getMyActivityStream
-- createMyPrivateProject
-- getMyProjectsList
-- getMyProjects
-- getTimezone
-- getVersion
-- getDefaultTaskColor
-- getDefaultTaskColors
-- getColorList
-- getProjectById
-- getTask
-- getTaskByReference
-- getAllTasks
-- openTask
-- closeTask
-- moveTaskPosition
-- createTask
-- updateTask
-- getBoard
-- getProjectActivity
-- getMyOverdueTasks
+
 
 Custom HTTP header
 ------------------
@@ -64,3 +42,14 @@ curl \
 -d '{"jsonrpc": "2.0", "method": "getAllProjects", "id": 1}' \
 http://localhost/kanboard/jsonrpc.php
 ```
+
+Authentication error
+--------------------
+
+If the credentials are wrong, you will receive a `401 Not Authorized` and the corresponding JSON response.
+
+
+Authorization error
+-------------------
+
+If the connected user is not allowed to access to the resource, you will receive a `403 Forbidden`.
diff --git a/doc/api-json-rpc.markdown b/doc/api-json-rpc.markdown
index bb14b008..0f922a7c 100644
--- a/doc/api-json-rpc.markdown
+++ b/doc/api-json-rpc.markdown
@@ -8,25 +8,25 @@ There are two types of API access:
 
 ### Application API
 
-- Access to the API with the user "jsonrpc" and the token available in settings
+- Access to the API with the user "jsonrpc" and the token available on the settings page
 - Access to all procedures
 - No permission checked
 - There is no user session on the server
+- No access to procedures that starts with "My..." (example: "getMe" or "getMyProjects")
 - Example of possible clients: tools to migrate/import data, create tasks from another system, etc...
 
 ### User API
 
 - Access to the API with the user credentials (username and password)
-- Access to a restricted set of procedures
-- The project permissions are checked
+- Application role and project permissions are checked for each procedure
 - A user session is created on the server
-- Example of possible clients: mobile/desktop application, command line utility, etc...
+- Example of possible clients: native mobile/desktop application, command line utility, etc...
 
 Security
 --------
 
-- Always use HTTPS with a valid certificate
-- If you make a mobile application, it's your job to store securely the user credentials on the device
+- Always use HTTPS with a valid certificate (avoid clear text communication)
+- If you make a mobile application, it's your responsability to store securely the user credentials on the device
 - After 3 authentication failure on the user api, the end-user have to unlock his account by using the login form
 - Two factor authentication is not yet available through the API
 
diff --git a/doc/api-project-permission-procedures.markdown b/doc/api-project-permission-procedures.markdown
index 2844ae3c..d5e9b066 100644
--- a/doc/api-project-permission-procedures.markdown
+++ b/doc/api-project-permission-procedures.markdown
@@ -272,3 +272,36 @@ Response example:
     "result": true
 }
 ```
+
+## getProjectUserRole
+
+- Purpose: **Get the role of a user for a given project**
+- Parameters:
+    - **project_id** (integer, required)
+    - **user_id** (integer, required)
+- Result on success: **role name**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "getProjectUserRole",
+    "id": 2114673298,
+    "params": [
+        "2",
+        "3"
+    ]
+}
+```
+
+Response example:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "id": 2114673298,
+    "result": "project-viewer"
+}
+```
diff --git a/doc/api-project-procedures.markdown b/doc/api-project-procedures.markdown
index 6cc1b15b..d375852c 100644
--- a/doc/api-project-procedures.markdown
+++ b/doc/api-project-procedures.markdown
@@ -7,6 +7,8 @@ API Project Procedures
 - Parameters:
     - **name** (string, required)
     - **description** (string, optional)
+    - **owner_id** (integer, optional)
+    - **identifier** (string, optional)
 - Result on success: **project_id**
 - Result on failure: **false**
 
@@ -183,9 +185,11 @@ Response example:
 
 - Purpose: **Update a project**
 - Parameters:
-    - **id** (integer, required)
-    - **name** (string, required)
+    - **project_id** (integer, required)
+    - **name** (string, optional)
     - **description** (string, optional)
+    - **owner_id** (integer, optional)
+    - **identifier** (string, optional)
 - Result on success: **true**
 - Result on failure: **false**
 
@@ -197,7 +201,7 @@ Request example:
     "method": "updateProject",
     "id": 1853996288,
     "params": {
-        "id": 1,
+        "project_id": 1,
         "name": "PHP client update"
     }
 }
diff --git a/doc/requirements.markdown b/doc/requirements.markdown
index 9943465a..f6c9b309 100644
--- a/doc/requirements.markdown
+++ b/doc/requirements.markdown
@@ -51,7 +51,7 @@ Kanboard is pre-configured to work with Apache (URL rewriting).
 
 | PHP Version    |
 |----------------|
-| PHP >= 5.3.3   |
+| PHP >= 5.3.9   |
 | PHP 5.4        |
 | PHP 5.5        |
 | PHP 5.6        |
diff --git a/doc/tests.markdown b/doc/tests.markdown
index 5e3d71d2..59177f87 100644
--- a/doc/tests.markdown
+++ b/doc/tests.markdown
@@ -9,7 +9,7 @@ Requirements
 ------------
 
 - Linux/Unix machine
-- PHP cli
+- PHP
 - PHPUnit installed
 - Mysql and Postgresql (optional)
 - Selenium (optional)
@@ -85,46 +85,37 @@ From your Kanboard directory, run the command `phpunit -c tests/units.postgres.x
 Integration Tests
 -----------------
 
-Acceptance tests (also known as end-to-end tests and sometimes functional tests) allow us to test the actual functionality of the browser using Selenium and PHPUnit.
+Integration tests are mainly used to test the API. 
+The test suites are making real HTTP calls to the application that run inside a container.
 
-The PHPUnit config file is `tests/acceptance.xml`.
-From your Kanboard directory, run the command `phpunit -c tests/units.sqlite.xml`.
-
-Actually only the API calls are tested.
-
-Real HTTP calls are made with those tests.
-So a local instance of Kanboard is necessary and must listen on `http://localhost:8000/`.
-
-All data will be removed/altered by the test suite.
-Moreover the script will reset and set a new API key.
+### Requirements
 
-1. Start a local instance of Kanboard `php -S 127.0.0.1:8000`
-2. Run the test suite from another terminal
+- PHP
+- Composer
+- Unix operating system (Mac OS or Linux)
+- Docker
+- Docker Compose
 
-The same method as above is used to run tests across different databases:
+### Running integration tests
 
-- Sqlite: `phpunit -c tests/integration.sqlite.xml`
-- Mysql: `phpunit -c tests/integration.mysql.xml`
-- Postgresql: `phpunit -c tests/integration.postgres.xml`
+Integration tests are using Docker containers. 
+There are 3 different environment available to run tests against each supported database.
 
-Example:
+You can use these commands to run each test suite:
 
 ```bash
-phpunit -c tests/integration.sqlite.xml
-
-PHPUnit 5.0.0 by Sebastian Bergmann and contributors.
+# Run tests with Sqlite
+make integration-test-sqlite
 
-...............................................................  63 / 135 ( 46%)
-............................................................... 126 / 135 ( 93%)
-.........                                                       135 / 135 (100%)
+# Run tests with Mysql
+make integration-test-mysql
 
-Time: 1.18 minutes, Memory: 14.75Mb
-
-OK (135 tests, 526 assertions)
+# Run tests with Postgres
+make integration-test-postgres
 ```
 
 Acceptance Tests
------------------
+----------------
 
 Acceptance tests (also sometimes known as end-to-end tests, and functional tests) test the actual functionality of the UI in a browser using Selenium.