AS1024/Kanboard-Prod
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add new API procedures for groups, roles and project permissions

Browse Source
This commit is contained in:
Frederic Guillot
2016-01-22 21:23:12 -05:00
parent f27bcec2d9
commit ad8fcf035a
26 changed files with 1122 additions and 266 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
doc/api-application-procedures.markdown
View File

@@ -229,3 +229,63 @@ Response example:
}
}
```
### getApplicationRoles
- Purpose: **Get the application roles**
- Parameters: none
- Result: **Dictionary of role => role_name**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "getApplicationRoles",
"id": 317154243
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 317154243,
"result": {
"app-admin": "Administrator",
"app-manager": "Manager",
"app-user": "User"
}
}
```
### getProjectRoles
- Purpose: **Get the project roles**
- Parameters: none
- Result: **Dictionary of role => role_name**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "getProjectRoles",
"id": 8981960
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 8981960,
"result": {
"project-manager": "Project Manager",
"project-member": "Project Member",
"project-viewer": "Project Viewer"
}
}
```

152
doc/api-group-member-procedures.markdown Normal file
View File

@@ -0,0 +1,152 @@
Group Member API Procedures
===========================
### getGroupMembers
- Purpose: **Get all members of a group**
- Parameters:
- **group_id** (integer, required)
- Result on success: **List of users**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "getGroupMembers",
"id": 1987176726,
"params": [
"1"
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 1987176726,
"result": [
{
"group_id": "1",
"user_id": "1",
"id": "1",
"username": "admin",
"is_ldap_user": "0",
"name": null,
"email": null,
"notifications_enabled": "0",
"timezone": null,
"language": null,
"disable_login_form": "0",
"notifications_filter": "4",
"nb_failed_login": "0",
"lock_expiration_date": "0",
"is_project_admin": "0",
"gitlab_id": null,
"role": "app-admin"
}
]
}
```
### addGroupMember
- Purpose: **Add a user to a group**
- Parameters:
- **group_id** (integer, required)
- **user_id** (integer, required)
- Result on success: **true**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "addGroupMember",
"id": 1589058273,
"params": [
1,
1
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 1589058273,
"result": true
}
```
### removeGroupMember
- Purpose: **Remove a user from a group**
- Parameters:
- **group_id** (integer, required)
- **user_id** (integer, required)
- Result on success: **true**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "removeGroupMember",
"id": 1730416406,
"params": [
1,
1
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 1730416406,
"result": true
}
```
### isGroupMember
- Purpose: **Check if a user is member of a group**
- Parameters:
- **group_id** (integer, required)
- **user_id** (integer, required)
- Result on success: **true**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "isGroupMember",
"id": 1052800865,
"params": [
1,
1
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 1052800865,
"result": false
}
```

174
doc/api-group-procedures.markdown Normal file
View File

@@ -0,0 +1,174 @@
Group API Procedures
====================
### createGroup
- Purpose: **Create a new group**
- Parameters:
- **name** (string, required)
- **external_id** (string, optional)
- Result on success: **link_id**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "createGroup",
"id": 1416806551,
"params": [
"My Group B",
"1234"
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 1416806551,
"result": 2
}
```
### updateGroup
- Purpose: **Update a group**
- Parameters:
- **group_id** (integer, required)
- **name** (string, optional)
- **external_id** (string, optional)
- Result on success: **true**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "updateGroup",
"id": 866078030,
"params": {
"group_id": "1",
"name": "ABC",
"external_id": "something"
}
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 866078030,
"result": true
}
```
### removeGroup
- Purpose: **Remove a group**
- Parameters:
- **group_id** (integer, required)
- Result on success: **true**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "removeGroup",
"id": 566000661,
"params": [
"1"
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 566000661,
"result": true
}
```
### getGroup
- Purpose: **Get one group**
- Parameters:
- **group_id** (integer, required)
- Result on success: **Group dictionary**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "getGroup",
"id": 1968647622,
"params": [
"1"
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 1968647622,
"result": {
"id": "1",
"external_id": "",
"name": "My Group A"
}
}
```
### getAllGroups
- Purpose: **Get all groups**
- Parameters: none
- Result on success: **list of groups**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "getAllGroups",
"id": 546070742
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 546070742,
"result": [
{
"id": "1",
"external_id": "",
"name": "My Group A"
},
{
"id": "2",
"external_id": "1234",
"name": "My Group B"
}
]
}
```

29
doc/api-json-rpc.markdown
View File

@@ -48,16 +48,19 @@ Usage
- [Authentication](api-authentication.markdown)
- [Examples](api-examples.markdown)
- [Application Procedures](api-application-procedures.markdown)
- [Project Procedures](api-project-procedures.markdown)
- [Board Procedures](api-board-procedures.markdown)
- [Swimlane Procedures](api-swimlane-procedures.markdown)
- [Category Procedures](api-category-procedures.markdown)
- [Automatic Action Procedures](api-action-procedures.markdown)
- [Task Procedures](api-task-procedures.markdown)
- [Subtask Procedures](api-subtask-procedures.markdown)
- [File Procedures](api-file-procedures.markdown)
- [Link Procedures](api-link-procedures.markdown)
- [Comment Procedures](api-comment-procedures.markdown)
- [User Procedures](api-user-procedures.markdown)
- [User API Access Procedures](api-me-procedures.markdown)
- [Application](api-application-procedures.markdown)
- [Projects](api-project-procedures.markdown)
- [Project Permissions](api-project-permission-procedures.markdown)
- [Boards](api-board-procedures.markdown)
- [Swimlanes](api-swimlane-procedures.markdown)
- [Categories](api-category-procedures.markdown)
- [Automatic Actions](api-action-procedures.markdown)
- [Tasks](api-task-procedures.markdown)
- [Subtasks](api-subtask-procedures.markdown)
- [Files](api-file-procedures.markdown)
- [Links](api-link-procedures.markdown)
- [Comments](api-comment-procedures.markdown)
- [Users](api-user-procedures.markdown)
- [Groups](api-group-procedures.markdown)
- [Group Members](api-group-member-procedures.markdown)
- [Me](api-me-procedures.markdown)

274
doc/api-project-permission-procedures.markdown Normal file
View File

@@ -0,0 +1,274 @@
Project Permission API Procedures
=================================
### getProjectUsers
- Purpose: **Get all members of a project**
- Parameters:
- **project_id** (integer, required)
- Result on success: **Dictionary of user_id => user name**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "getProjectUsers",
"id": 1601016721,
"params": [
"1"
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 1601016721,
"result": {
"1": "admin"
}
}
```
### getAssignableUsers
- Purpose: **Get users that can be assigned to a task for a project** (all members except viewers)
- Parameters:
- **project_id** (integer, required)
- **prepend_unassigned** (boolean, optional, default is false)
- Result on success: **Dictionary of user_id => user name**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "getAssignableUsers",
"id": 658294870,
"params": [
"1"
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 658294870,
"result": {
"1": "admin"
}
}
```
### addProjectUser
- Purpose: **Grant access to a project for a user**
- Parameters:
- **project_id** (integer, required)
- **user_id** (integer, required)
- **role** (string, optional)
- Result on success: **true**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "addProjectUser",
"id": 1294688355,
"params": [
"1",
"1",
"project-viewer"
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 1294688355,
"result": true
}
```
### addProjectGroup
- Purpose: **Grant access to a project for a group**
- Parameters:
- **project_id** (integer, required)
- **group_id** (integer, required)
- **role** (string, optional)
- Result on success: **true**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "addProjectGroup",
"id": 1694959089,
"params": [
"1",
"1"
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 1694959089,
"result": true
}
```
### removeProjectUser
- Purpose: **Revoke user access to a project**
- Parameters:
- **project_id** (integer, required)
- **user_id** (integer, required)
- Result on success: **true**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "removeProjectUser",
"id": 645233805,
"params": [
1,
1
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 645233805,
"result": true
}
```
### removeProjectGroup
- Purpose: **Revoke group access to a project**
- Parameters:
- **project_id** (integer, required)
- **group_id** (integer, required)
- Result on success: **true**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "removeProjectGroup",
"id": 557146966,
"params": [
1,
1
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 557146966,
"result": true
}
```
### changeProjectUserRole
- Purpose: **Change role of a user for a project**
- Parameters:
- **project_id** (integer, required)
- **user_id** (integer, required)
- **role** (string, required)
- Result on success: **true**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "changeProjectUserRole",
"id": 193473170,
"params": [
"1",
"1",
"project-viewer"
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 193473170,
"result": true
}
```
### changeProjectGroupRole
- Purpose: **Change role of a group for a project**
- Parameters:
- **project_id** (integer, required)
- **group_id** (integer, required)
- **role** (string, required)
- Result on success: **true**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "changeProjectGroupRole",
"id": 2114673298,
"params": [
"1",
"1",
"project-viewer"
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 2114673298,
"result": true
}
```

101
doc/api-project-procedures.markdown
View File

@@ -409,104 +409,3 @@ Request example:
]
}
```
### getMembers
- Purpose: **Get members of a project**
- Parameters:
- **project_id** (integer, required)
- Result on success: Key/value pair of user_id and username
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "getMembers",
"id": 1944388643,
"params": [
1
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 1944388643,
"result": {
"1": "user1",
"2": "user2",
"3": "user3"
}
}
```
### revokeUser
- Purpose: **Revoke user access for a given project**
- Parameters:
- **project_id** (integer, required)
- **user_id** (integer, required)
- Result on success: **true**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "revokeUser",
"id": 251218350,
"params": [
1,
2
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 251218350,
"result": true
}
```
### allowUser
- Purpose: **Grant user access for a given project**
- Parameters:
- **project_id** (integer, required)
- **user_id** (integer, required)
- Result on success: **true**
- Result on failure: **false**
Request example:
```json
{
"jsonrpc": "2.0",
"method": "allowUser",
"id": 2111451404,
"params": [
1,
2
]
}
```
Response example:
```json
{
"jsonrpc": "2.0",
"id": 2111451404,
"result": true
}
```

128
doc/tests.markdown
View File

@@ -1,7 +1,7 @@
How to run units and functional tests?
======================================
Automated tests
===============
[PHPUnit](https://phpunit.de/) is used to run automatic tests on Kanboard.
[PHPUnit](https://phpunit.de/) is used to run automated tests on Kanboard.
You can run tests across different databases (Sqlite, Mysql and Postgresql) to be sure that the result is the same everywhere.
@@ -9,31 +9,18 @@ Requirements
------------
- Linux/Unix machine
- PHP command line
- PHP cli
- PHPUnit installed
- Mysql and Postgresql (optional)
Install the latest version of PHPUnit
-------------------------------------
Unit Tests
----------
Simply download the PHPUnit PHAR et copy the file somewhere in your `$PATH`:
```bash
wget https://phar.phpunit.de/phpunit.phar
chmod +x phpunit.phar
sudo mv phpunit.phar /usr/local/bin/phpunit
phpunit --version
PHPUnit 4.2.6 by Sebastian Bergmann.
```
Running unit tests
------------------
### Testing with Sqlite
### Test with Sqlite
Sqlite tests use a in-memory database, nothing is written on the file system.
The config file is `tests/units.sqlite.xml`.
The PHPUnit config file is `tests/units.sqlite.xml`.
From your Kanboard directory, run the command `phpunit -c tests/units.sqlite.xml`.
Example:
@@ -41,21 +28,26 @@ Example:
```bash
phpunit -c tests/units.sqlite.xml
PHPUnit 4.2.6 by Sebastian Bergmann.
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.
Configuration read from /Volumes/Devel/apps/kanboard/tests/units.sqlite.xml
............................................................... 63 / 649 ( 9%)
............................................................... 126 / 649 ( 19%)
............................................................... 189 / 649 ( 29%)
............................................................... 252 / 649 ( 38%)
............................................................... 315 / 649 ( 48%)
............................................................... 378 / 649 ( 58%)
............................................................... 441 / 649 ( 67%)
............................................................... 504 / 649 ( 77%)
............................................................... 567 / 649 ( 87%)
............................................................... 630 / 649 ( 97%)
................... 649 / 649 (100%)
................................................................. 65 / 74 ( 87%)
.........
Time: 1.22 minutes, Memory: 151.25Mb
Time: 9.05 seconds, Memory: 17.75Mb
OK (74 tests, 6145 assertions)
OK (649 tests, 43595 assertions)
```
**NOTE:** PHPUnit is already included in the Vagrant environment
### Testing with Mysql
### Test with Mysql
You must have Mysql or MariaDb installed on localhost.
@@ -68,27 +60,10 @@ By default, those credentials are used:
For each execution the database is dropped and created again.
The config file is `tests/units.mysql.xml`.
The PHPUnit config file is `tests/units.mysql.xml`.
From your Kanboard directory, run the command `phpunit -c tests/units.mysql.xml`.
Example:
```bash
phpunit -c tests/units.mysql.xml
PHPUnit 4.2.6 by Sebastian Bergmann.
Configuration read from /Volumes/Devel/apps/kanboard/tests/units.mysql.xml
................................................................. 65 / 74 ( 87%)
.........
Time: 49.77 seconds, Memory: 17.50Mb
OK (74 tests, 6145 assertions)
```
### Testing with Postgresql
### Test with Postgresql
You must have Postgresql installed on localhost.
@@ -100,37 +75,20 @@ By default, those credentials are used:
- Database: **kanboard_unit_test**
Be sure to allow the user `postgres` to create and drop databases.
For each execution the database is dropped and created again.
The database is recreated for each execution.
The config file is `tests/units.postgres.xml`.
The PHPUnit config file is `tests/units.postgres.xml`.
From your Kanboard directory, run the command `phpunit -c tests/units.postgres.xml`.
Example:
```bash
phpunit -c tests/units.postgres.xml
PHPUnit 4.2.6 by Sebastian Bergmann.
Configuration read from /Volumes/Devel/apps/kanboard/tests/units.postgres.xml
................................................................. 65 / 74 ( 87%)
.........
Time: 52.66 seconds, Memory: 17.50Mb
OK (74 tests, 6145 assertions)
```
Running functionals tests
-------------------------
Integration Tests
-----------------
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`.
So a local instance of Kanboard is necessary and must listen on `http://localhost:8000/`.
Don't forget that all data will be removed/altered by the test suite.
All data will be removed/altered by the test suite.
Moreover the script will reset and set a new API key.
1. Start a local instance of Kanboard `php -S 127.0.0.1:8000`
@@ -138,27 +96,27 @@ Moreover the script will reset and set a new API key.
The same method as above is used to run tests across different databases:
- Sqlite: `phpunit -c tests/functionals.sqlite.xml`
- Mysql: `phpunit -c tests/functionals.mysql.xml`
- Postgresql: `phpunit -c tests/functionals.postgres.xml`
- Sqlite: `phpunit -c tests/integration.sqlite.xml`
- Mysql: `phpunit -c tests/integration.mysql.xml`
- Postgresql: `phpunit -c tests/integration.postgres.xml`
Example:
```bash
phpunit -c tests/functionals.sqlite.xml
phpunit -c tests/integration.sqlite.xml
PHPUnit 4.2.6 by Sebastian Bergmann.
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.
Configuration read from /Volumes/Devel/apps/kanboard/tests/functionals.sqlite.xml
............................................................... 63 / 135 ( 46%)
............................................................... 126 / 135 ( 93%)
......... 135 / 135 (100%)
..........................................
Time: 1.18 minutes, Memory: 14.75Mb
Time: 1.72 seconds, Memory: 4.25Mb
OK (42 tests, 160 assertions)
OK (135 tests, 526 assertions)
```
Continuous Integration with Travis-ci
Continuous Integration with Travis-CI
-------------------------------------
After each commit pushed on the main repository, unit tests are executed across 5 different versions of PHP:
@@ -171,6 +129,4 @@ After each commit pushed on the main repository, unit tests are executed across
Each version of PHP is tested against the 3 supported database: Sqlite, Mysql and Postgresql.
That mean we run 15 jobs each time the repository is updated. The execution time is around 25 minutes.
The Travis config file `.travis.yml` is located on the root directory of Kanboard.