Andreas/wekan
1
0
Fork 0
mirror of https://github.com/wekan/wekan.git synced 2025-12-16 23:40:13 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Reorganized Docs. In Progress.

Browse source
This commit is contained in:
Lauri Ojansivu 2024-06-27 11:08:43 +03:00
parent 1961e22cbd
commit ce89ff4833
202 changed files with 0 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

41
docs/API/New-card-with-Python3-and-REST-API.md Normal file
View file

@ -0,0 +1,41 @@
Wekan provides a python script to ease the call of the REST API from command line interface.
# Context
- [API Login to get Bearer token](REST-API#example-call---as-form-data)
- [API docs and examples for various programming languages](https://wekan.github.io/api/), there is Boards / Export for exporting board with API
- In the right menu, scroll down REST API Docs etc links =====>
- Wekan-Gogs integration with Node.js https://github.com/wekan/wekan-gogs
# Install
You need python3.
Windows
```
choco install python3
# REBOOT
pip3 install pip --upgrade
pip3 install json
python3 wekan.py
```
Debian/Ubuntu
```
sudo apt-get -y install python3 python3-pip python3-simplejson
sudo pip3 install pip --upgrade
chmod +x wekan.py
./wekan.py
```
# Usage
Copy the api.py script to you machine. [Newest Wekan Python CLI api.py here](https://raw.githubusercontent.com/wekan/wekan/master/api.py).
Then, in this script, look for and change:
- wekanurl: https://boards.example.com => Your Wekan URL
- username (could be username or username@example.com)
- Only works with password login admin user. Does not work with LDAP, OAuth2 etc.
Keep in mind your Wekan credentials are potentially accessible in this file.
Then call it without any argument to see if everything is all right. You should just get usage examples.

56
docs/API/REST-API-Boards.md Normal file
View file

@ -0,0 +1,56 @@
# Disclaimer
This page tries to be as up to date as possible. If you see something wrong here, feel free to update the page and help other people like you, that greatly depends on our APIs. If you don't feel comfortable doing this kind of changes, please contact us by creating an [issue](https://github.com/wekan/wekan/issues/new).
## Information about boards of user
```
curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
http://localhost:3000/api/users/XQMZgynx9M79qTtQc/boards
```
## Add/Remove Board Member and Change Role
[Add/Remove Board Member and Change Role admin/normal/nocomments/commentonly](REST-API-Role).
## The admin takes the ownership of ALL boards of the user (archived and not archived) where the user is admin on.
| URL | Requires Admin Auth | HTTP Method |
| :--- | :--- | :--- |
| `/api/users/:id` | `yes` | `PUT` |
```shell
curl -H "Authorization: Bearer t7iYB86mXoLfP_XsMegxF41oKT7iiA9lDYiKVtXcctl" \
-H "Content-type:application/json" \
-X PUT \
http://localhost:3000/api/users/ztKvBTzCqmyJ77on8 \
-d '{ "action": "takeOwnership" }'
```
## Create board
Required:
- "title":"Board title here"
- "owner":"ABCDE12345" <= User ID in Wekan. Not username or email.
Optional, and defaults:
- "isAdmin":"true"
- "isActive":"true"
- "isNoComments":"false"
- "isCommentOnly":"false"
- "permission":"private" <== Set to "public" if you want public Wekan board
- "color":"belize" <== Board color: belize, nephritis, pomegranate, pumpkin, wisteria, midnight.
<img src="https://wekan.github.io/board-colors.png" width="40%" alt="Wekan logo" />
Example:
```
curl -H "Authorization: Bearer t7iYB86mXoLfP_XsMegxF41oKT7iiA9lDYiKVtXcctl" \
-H "Content-type:application/json" \
-X POST \
http://localhost:3000/api/boards \
-d '{"title":"Board title here","owner":"ABCDE12345","permission":"private","color":"nephritis"}'
```
## In Wekan code
If you believe that code is the best documentation, be our guest: [models/cards.js](https://github.com/wekan/wekan/blob/main/models/boards.js "Board API code")

94
docs/API/REST-API-Cards.md Normal file
View file

@ -0,0 +1,94 @@
# Disclaimer
This page tries to be as up to date as possible. If you see something wrong here, feel free to update the page and help other people like you, that greatly depends on our APIs. If you don't feel comfortable doing this kind of changes, please contact us by creating an [issue](https://github.com/wekan/wekan/issues/new).
# Retrieve cards by swimlane id
| API URL / Code Link | Requires Admin Auth | HTTP Method |
| :--- | :--- | :--- |
| [/api/boards/:boardId/swimlanes/:swimlaneId/cards](https://github.com/wekan/wekan/blob/c115046a7c86b30ab5deb8762d3ef7a5ea3f4f90/models/cards.js#L487) | `yes` | `GET` |
```shell
curl -H "Authorization: Bearer t7iYB86mXoLfP_XsMegxF41oKT7iiA9lDYiKVtXcctl" \
-X GET \
http://localhost:3000/api/boards/YRgy7Ku6uLFv2pYwZ/swimlanes/PgTuf6sFJsaxto5dC/cards
```
## Result example
```shell
{
"_id": "AzEeHS7KAGeYZCcak",
"title": "Create Auth Code",
"description": "Create Auth Code for application.",
"listId": "RPRtDTQMKpShpgqoj"
},
{
...
```
# Add Card to List-Board-Swimlane
| API URL / Code Link | Requires Admin Auth | HTTP Method |
| :--- | :--- | :--- |
| [/api/boards/:boardId/lists/:listId/cards](https://github.com/wekan/wekan/blob/c115046a7c86b30ab5deb8762d3ef7a5ea3f4f90/models/cards.js#L487) | `yes` | `POST` |
```shell
curl -H "Authorization: Bearer t7iYB86mXoLfP_XsMegxF41oKT7iiA9lDYiKVtXcctl" \
-H "Content-type:application/json" \
-X POST \
http://localhost:3000/api/boards/YRgy7Ku6uLFv2pYwZ/lists/PgTuf6sFJsaxto5dC/cards \
-d '{ "title": "Card title text", "description": "Card description text", "authorId": "The appropriate existing userId", "swimlaneId": "The destination swimlaneId" }'
```
## Result example
The new card's ID is returned in the format:
```json
{
"_id": "W9m9YxQKT6zZrKzRW"
}
```
# Update a card
You can change (any of) the card's title, list, and description.
| API URL / Code Link | Requires Admin Auth | HTTP Method |
| :--- | :--- | :--- |
| [/api/boards/:boardId/lists/:fromListId/cards/:cardId](https://github.com/wekan/wekan/blob/c115046a7c86b30ab5deb8762d3ef7a5ea3f4f90/models/cards.js#L520) | `yes` | `PUT` |
```shell
curl -H "Authorization: Bearer t7iYB86mXoLfP_XsMegxF41oKT7iiA9lDYiKVtXcctl" \
-H "Content-type:application/json" \
-X PUT \
http://localhost:3000/api/boards/YRgy7Ku6uLFv2pYwZ/lists/PgTuf6sFJsaxto5dC/cards/ssrNX9CvXvPxuC5DE \
-d '{ "title": "New title text", "listId": "New destination listId", "description": "New description text" }'
```
## Result example
The card's ID is returned in the format:
```json
{
"_id": "W9m9YxQKT6zZrKzRW"
}
```
# Delete a card
| API URL / Code Link | Requires Admin Auth | HTTP Method |
| :--- | :--- | :--- |
| [/api/boards/:boardId/lists/:listId/cards/:cardId](https://github.com/wekan/wekan/blob/c115046a7c86b30ab5deb8762d3ef7a5ea3f4f90/models/cards.js#L554) | `yes` | `DELETE` |
```shell
curl -H "Authorization: Bearer t7iYB86mXoLfP_XsMegxF41oKT7iiA9lDYiKVtXcctl" \
-H "Content-type:application/json" \
-X DELETE \
http://localhost:3000/api/boards/YRgy7Ku6uLFv2pYwZ/lists/PgTuf6sFJsaxto5dC/cards/ssrNX9CvXvPxuC5DE \
-d '{ "authorId": "the appropriate existing userId"}'
```
## Result example
The card's ID is returned in the format:
```json
{
"_id": "W9m9YxQKT6zZrKzRW"
}
```
# In Wekan code
If you believe that code is the best documentation, be our guest: [models/cards.js](https://github.com/wekan/wekan/blob/main/models/cards.js "Card API code")

148
docs/API/REST-API-Checklists.md Normal file
View file

@ -0,0 +1,148 @@
## In Wekan code
## 1) Checklists
wekan/models/checklists.js at bottom:
```
JsonRoutes.add('GET', '/api/boards/:boardId/cards/:cardId/checklists', function (req, res) {
Authentication.checkUserId( req.userId);
const paramCardId = req.params.cardId;
const checklists = Checklists.find({ cardId: paramCardId }).map(function (doc) {
return {
_id: doc._id,
title: doc.title,
};
});
if (checklists) {
JsonRoutes.sendResult(res, {
code: 200,
data: checklists,
});
} else {
JsonRoutes.sendResult(res, {
code: 500,
});
}
});
JsonRoutes.add('GET', '/api/boards/:boardId/cards/:cardId/checklists/:checklistId', function (req, res) {
Authentication.checkUserId( req.userId);
const paramChecklistId = req.params.checklistId;
const paramCardId = req.params.cardId;
const checklist = Checklists.findOne({ _id: paramChecklistId, cardId: paramCardId });
if (checklist) {
checklist.items = ChecklistItems.find({checklistId: checklist._id}).map(function (doc) {
return {
_id: doc._id,
title: doc.title,
isFinished: doc.isFinished,
};
});
JsonRoutes.sendResult(res, {
code: 200,
data: checklist,
});
} else {
JsonRoutes.sendResult(res, {
code: 500,
});
}
});
JsonRoutes.add('POST', '/api/boards/:boardId/cards/:cardId/checklists', function (req, res) {
Authentication.checkUserId( req.userId);
const paramCardId = req.params.cardId;
const id = Checklists.insert({
title: req.body.title,
cardId: paramCardId,
sort: 0,
});
if (id) {
req.body.items.forEach(function (item, idx) {
ChecklistItems.insert({
cardId: paramCardId,
checklistId: id,
title: item.title,
sort: idx,
});
});
JsonRoutes.sendResult(res, {
code: 200,
data: {
_id: id,
},
});
} else {
JsonRoutes.sendResult(res, {
code: 400,
});
}
});
JsonRoutes.add('DELETE', '/api/boards/:boardId/cards/:cardId/checklists/:checklistId', function (req, res) {
Authentication.checkUserId( req.userId);
const paramChecklistId = req.params.checklistId;
Checklists.remove({ _id: paramChecklistId });
JsonRoutes.sendResult(res, {
code: 200,
data: {
_id: paramChecklistId,
},
});
});
```
### 2) Checklist Items
wekan/models/checklistItems.js at bottom:
```
JsonRoutes.add('GET', '/api/boards/:boardId/cards/:cardId/checklists/:checklistId/items/:itemId', function (req, res) {
Authentication.checkUserId( req.userId);
const paramItemId = req.params.itemId;
const checklistItem = ChecklistItems.findOne({ _id: paramItemId });
if (checklistItem) {
JsonRoutes.sendResult(res, {
code: 200,
data: checklistItem,
});
} else {
JsonRoutes.sendResult(res, {
code: 500,
});
}
});
JsonRoutes.add('PUT', '/api/boards/:boardId/cards/:cardId/checklists/:checklistId/items/:itemId', function (req, res) {
Authentication.checkUserId( req.userId);
const paramItemId = req.params.itemId;
if (req.body.hasOwnProperty('isFinished')) {
ChecklistItems.direct.update({_id: paramItemId}, {$set: {isFinished: req.body.isFinished}});
}
if (req.body.hasOwnProperty('title')) {
ChecklistItems.direct.update({_id: paramItemId}, {$set: {title: req.body.title}});
}
JsonRoutes.sendResult(res, {
code: 200,
data: {
_id: paramItemId,
},
});
});
JsonRoutes.add('DELETE', '/api/boards/:boardId/cards/:cardId/checklists/:checklistId/items/:itemId', function (req, res) {
Authentication.checkUserId( req.userId);
const paramItemId = req.params.itemId;
ChecklistItems.direct.remove({ _id: paramItemId });
JsonRoutes.sendResult(res, {
code: 200,
data: {
_id: paramItemId,
},
});
```

33
docs/API/REST-API-Code.md Normal file
View file

@ -0,0 +1,33 @@
## Using Meteor with REST API
### 1) Adding API
```
meteor add simple:json-routes
```
https://atmospherejs.com/simple/json-routes
https://github.com/wekan/wekan/blob/main/.meteor/packages#L139
### 2) API code
At models directory:
https://github.com/wekan/wekan/blob/main/models/users.js#L2018
### 3) Login to API as JSON
https://github.com/wekan/wekan/wiki/REST-API#example-call---as-json
Also see at wiki right menu about REST API.
### 4) Use Python3 CLI to login to API and do REST API action
https://github.com/wekan/wekan/blob/main/api.py
### 4) API Docs
https://wekan.github.io/api/
Building API Docs: https://github.com/wekan/wekan/blob/main/releases/rebuild-docs.sh

78
docs/API/REST-API-Custom-Fields.md Normal file
View file

@ -0,0 +1,78 @@
1) Login as Admin user as Form Data to get Bearer token
https://github.com/wekan/wekan/wiki/REST-API#example-call---as-form-data
2) There needs to be Custom Field added to board
https://wekan.github.io/api/v4.42/#wekan-rest-api-customfields
3) Custom Field at board and card will have same `_id`
https://wekan.github.io/api/v4.42/#put_board_list_card
4) When writing Custom Field value to card, like text field, content type needs to be "application/json" and the string needs to be an array:
```
-d '{ "customFields" : [ { "_id" : "oZHkpcaxDHnbkbqGo", "value" : "foobar" } ] }'
```
5) For other types of Custom Fields, you can look at Custom Field structure from MongoDB database with [nosqlbooster](https://nosqlbooster.com/downloads) that can also login through ssh to server Wekan snap MongoDB port 27019
## In Wekan code (old)
wekan/models/customFields.js , at bottom
```
//CUSTOM FIELD REST API
if (Meteor.isServer) {
JsonRoutes.add('GET', '/api/boards/:boardId/custom-fields', function (req, res) {
Authentication.checkUserId( req.userId);
const paramBoardId = req.params.boardId;
JsonRoutes.sendResult(res, {
code: 200,
data: CustomFields.find({ boardId: paramBoardId }),
});
});
JsonRoutes.add('GET', '/api/boards/:boardId/custom-fields/:customFieldId', function (req, res) {
Authentication.checkUserId( req.userId);
const paramBoardId = req.params.boardId;
const paramCustomFieldId = req.params.customFieldId;
JsonRoutes.sendResult(res, {
code: 200,
data: CustomFields.findOne({ _id: paramCustomFieldId, boardId: paramBoardId }),
});
});
JsonRoutes.add('POST', '/api/boards/:boardId/custom-fields', function (req, res) {
Authentication.checkUserId( req.userId);
const paramBoardId = req.params.boardId;
const id = CustomFields.direct.insert({
name: req.body.name,
type: req.body.type,
settings: req.body.settings,
showOnCard: req.body.showOnCard,
boardId: paramBoardId,
});
const customField = CustomFields.findOne({_id: id, boardId: paramBoardId });
customFieldCreation(req.body.authorId, customField);
JsonRoutes.sendResult(res, {
code: 200,
data: {
_id: id,
},
});
});
JsonRoutes.add('DELETE', '/api/boards/:boardId/custom-fields/:customFieldId', function (req, res) {
Authentication.checkUserId( req.userId);
const paramBoardId = req.params.boardId;
const id = req.params.customFieldId;
CustomFields.remove({ _id: id, boardId: paramBoardId });
JsonRoutes.sendResult(res, {
code: 200,
data: {
_id: id,
},
});
});
}
```

191
docs/API/REST-API-Integrations.md Normal file
View file

@ -0,0 +1,191 @@
## In Wekan code
wekan/models/integrations.js at bottom
```
// Get all integrations in board
JsonRoutes.add('GET', '/api/boards/:boardId/integrations', function(req, res) {
try {
const paramBoardId = req.params.boardId;
Authentication.checkBoardAccess(req.userId, paramBoardId);
const data = Integrations.find({ boardId: paramBoardId }, { fields: { token: 0 } }).map(function(doc) {
return doc;
});
JsonRoutes.sendResult(res, {code: 200, data});
}
catch (error) {
JsonRoutes.sendResult(res, {
code: 200,
data: error,
});
}
});
// Get a single integration in board
JsonRoutes.add('GET', '/api/boards/:boardId/integrations/:intId', function(req, res) {
try {
const paramBoardId = req.params.boardId;
const paramIntId = req.params.intId;
Authentication.checkBoardAccess(req.userId, paramBoardId);
JsonRoutes.sendResult(res, {
code: 200,
data: Integrations.findOne({ _id: paramIntId, boardId: paramBoardId }, { fields: { token: 0 } }),
});
}
catch (error) {
JsonRoutes.sendResult(res, {
code: 200,
data: error,
});
}
});
// Create a new integration
JsonRoutes.add('POST', '/api/boards/:boardId/integrations', function(req, res) {
try {
const paramBoardId = req.params.boardId;
Authentication.checkBoardAccess(req.userId, paramBoardId);
const id = Integrations.insert({
userId: req.userId,
boardId: paramBoardId,
url: req.body.url,
});
JsonRoutes.sendResult(res, {
code: 200,
data: {
_id: id,
},
});
}
catch (error) {
JsonRoutes.sendResult(res, {
code: 200,
data: error,
});
}
});
// Edit integration data
JsonRoutes.add('PUT', '/api/boards/:boardId/integrations/:intId', function (req, res) {
try {
const paramBoardId = req.params.boardId;
const paramIntId = req.params.intId;
Authentication.checkBoardAccess(req.userId, paramBoardId);
if (req.body.hasOwnProperty('enabled')) {
const newEnabled = req.body.enabled;
Integrations.direct.update({_id: paramIntId, boardId: paramBoardId},
{$set: {enabled: newEnabled}});
}
if (req.body.hasOwnProperty('title')) {
const newTitle = req.body.title;
Integrations.direct.update({_id: paramIntId, boardId: paramBoardId},
{$set: {title: newTitle}});
}
if (req.body.hasOwnProperty('url')) {
const newUrl = req.body.url;
Integrations.direct.update({_id: paramIntId, boardId: paramBoardId},
{$set: {url: newUrl}});
}
if (req.body.hasOwnProperty('token')) {
const newToken = req.body.token;
Integrations.direct.update({_id: paramIntId, boardId: paramBoardId},
{$set: {token: newToken}});
}
if (req.body.hasOwnProperty('activities')) {
const newActivities = req.body.activities;
Integrations.direct.update({_id: paramIntId, boardId: paramBoardId},
{$set: {activities: newActivities}});
}
JsonRoutes.sendResult(res, {
code: 200,
data: {
_id: paramIntId,
},
});
}
catch (error) {
JsonRoutes.sendResult(res, {
code: 200,
data: error,
});
}
});
// Delete subscribed activities
JsonRoutes.add('DELETE', '/api/boards/:boardId/integrations/:intId/activities', function (req, res) {
try {
const paramBoardId = req.params.boardId;
const paramIntId = req.params.intId;
const newActivities = req.body.activities;
Authentication.checkBoardAccess(req.userId, paramBoardId);
Integrations.direct.update({_id: paramIntId, boardId: paramBoardId},
{$pullAll: {activities: newActivities}});
JsonRoutes.sendResult(res, {
code: 200,
data: Integrations.findOne({_id: paramIntId, boardId: paramBoardId}, { fields: {_id: 1, activities: 1}}),
});
}
catch (error) {
JsonRoutes.sendResult(res, {
code: 200,
data: error,
});
}
});
// Add subscribed activities
JsonRoutes.add('POST', '/api/boards/:boardId/integrations/:intId/activities', function (req, res) {
try {
const paramBoardId = req.params.boardId;
const paramIntId = req.params.intId;
const newActivities = req.body.activities;
Authentication.checkBoardAccess(req.userId, paramBoardId);
Integrations.direct.update({_id: paramIntId, boardId: paramBoardId},
{$addToSet: {activities: { $each: newActivities}}});
JsonRoutes.sendResult(res, {
code: 200,
data: Integrations.findOne({_id: paramIntId, boardId: paramBoardId}, { fields: {_id: 1, activities: 1}}),
});
}
catch (error) {
JsonRoutes.sendResult(res, {
code: 200,
data: error,
});
}
});
// Delete integration
JsonRoutes.add('DELETE', '/api/boards/:boardId/integrations/:intId', function (req, res) {
try {
const paramBoardId = req.params.boardId;
const paramIntId = req.params.intId;
Authentication.checkBoardAccess(req.userId, paramBoardId);
Integrations.direct.remove({_id: paramIntId, boardId: paramBoardId});
JsonRoutes.sendResult(res, {
code: 200,
data: {
_id: paramIntId,
},
});
}
catch (error) {
JsonRoutes.sendResult(res, {
code: 200,
data: error,
});
}
});
```

89
docs/API/REST-API-Lists.md Normal file
View file

@ -0,0 +1,89 @@
## In Wekan code
wekan/models/lists.js at bottom:
```
JsonRoutes.add('GET', '/api/boards/:boardId/lists', function (req, res) {
try {
const paramBoardId = req.params.boardId;
Authentication.checkBoardAccess( req.userId, paramBoardId);
JsonRoutes.sendResult(res, {
code: 200,
data: Lists.find({ boardId: paramBoardId, archived: false }).map(function (doc) {
return {
_id: doc._id,
title: doc.title,
};
}),
});
}
catch (error) {
JsonRoutes.sendResult(res, {
code: 200,
data: error,
});
}
});
JsonRoutes.add('GET', '/api/boards/:boardId/lists/:listId', function (req, res) {
try {
const paramBoardId = req.params.boardId;
const paramListId = req.params.listId;
Authentication.checkBoardAccess( req.userId, paramBoardId);
JsonRoutes.sendResult(res, {
code: 200,
data: Lists.findOne({ _id: paramListId, boardId: paramBoardId, archived: false }),
});
}
catch (error) {
JsonRoutes.sendResult(res, {
code: 200,
data: error,
});
}
});
JsonRoutes.add('POST', '/api/boards/:boardId/lists', function (req, res) {
try {
Authentication.checkUserId( req.userId);
const paramBoardId = req.params.boardId;
const id = Lists.insert({
title: req.body.title,
boardId: paramBoardId,
});
JsonRoutes.sendResult(res, {
code: 200,
data: {
_id: id,
},
});
}
catch (error) {
JsonRoutes.sendResult(res, {
code: 200,
data: error,
});
}
});
JsonRoutes.add('DELETE', '/api/boards/:boardId/lists/:listId', function (req, res) {
try {
Authentication.checkUserId( req.userId);
const paramBoardId = req.params.boardId;
const paramListId = req.params.listId;
Lists.remove({ _id: paramListId, boardId: paramBoardId });
JsonRoutes.sendResult(res, {
code: 200,
data: {
_id: paramListId,
},
});
}
catch (error) {
JsonRoutes.sendResult(res, {
code: 200,
data: error,
});
}
});
```

82
docs/API/REST-API-Role.md Normal file
View file

@ -0,0 +1,82 @@
# Change Role at Web UI
BoardAdmin can change role of user at right sidebar / click avatar / select role like Admin, Normal, etc.
# Change Role with API
- https://wekan.github.io/api/
- api.py at https://github.com/wekan/wekan
- Login to API https://github.com/wekan/wekan/wiki/REST-API#example-call---as-json
# Disclaimer
This page tries to be as up to date as possible. If you see something wrong here, feel free to update the page and help other people like you, that greatly depends on our APIs. If you don't feel comfortable doing this kind of changes, please contact us by creating an [issue](https://github.com/wekan/wekan/issues/new).
## Add New Board Member with Role
This example adds with normal role. See examples below for other roles.
```
curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
-H "Content-type:application/json" \
-X POST \
http://localhost:3000/api/boards/BOARD-ID-HERE/members/USER-ID-HERE/add \
-d '{"action": "add","isAdmin": "false", "isNoComments":"false", "isCommentOnly": "false", "isWorker": "false" }'
```
like
```
/api/boards/{boardid}/members/{MEMBERID}/add Body{ "action" : add, "isadmin" : false ...........
```
## Remove Member from Board
```
curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
-H "Content-type:application/json" \
-X POST \
http://localhost:3000/api/boards/BOARD-ID-HERE/members/USER-ID-HERE/remove \
-d '{"action": "remove"}'
```
# Change Role of Existing Board Member
## Admin
```
curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
-H "Content-type:application/json" \
-X POST \
http://localhost:3000/api/boards/BOARD-ID-HERE/members/USER-ID-HERE \
-d '{"isAdmin": "true", "isNoComments":"false", "isCommentOnly": "false", "isWorker": "false"}'
```
## Normal
```
curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
-H "Content-type:application/json" \
-X POST \
http://localhost:3000/api/boards/BOARD-ID-HERE/members/USER-ID-HERE \
-d '{"isAdmin": "false", "isNoComments":"false", "isCommentOnly": "false", "isWorker": "false"}'
```
## No Comments
```
curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
-H "Content-type:application/json" \
-X POST \
http://localhost:3000/api/boards/BOARD-ID-HERE/members/USER-ID-HERE \
-d '{"isAdmin": "false", "isNoComments":"true", "isCommentOnly": "false", "isWorker": "false"}'
```
## Comment Only
```
curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
-H "Content-type:application/json" \
-X POST \
http://localhost:3000/api/boards/BOARD-ID-HERE/members/USER-ID-HERE \
-d '{"isAdmin": "false", "isNoComments":"false", "isCommentOnly": "true", "isWorker": "false"}'
```
## Worker
- Can: move cards, can assign himself to card, can comment.
- Cannot: anything else including revoke card, change settings, create/delete/edit cards/tags and so on...
```
curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
-H "Content-type:application/json" \
-X POST \
http://localhost:3000/api/boards/BOARD-ID-HERE/members/USER-ID-HERE \
-d '{"isAdmin": "false", "isNoComments":"false", "isCommentOnly": "false", "isWorker": "true"}'
```

54
docs/API/REST-API-Swimlanes.md Normal file
View file

@ -0,0 +1,54 @@
# Disclaimer
This page tries to be as up to date as possible. If you see something wrong here, feel free to update the page and help other people like you, that greatly depends on our APIs. If you don't feel comfortable doing this kind of changes, please contact us by creating an [issue](https://github.com/wekan/wekan/issues/new).
# Retrieve cards by swimlane id
Please somebody add example by looking this:
[Issue](https://github.com/wekan/wekan/issues/1934) and [code](https://github.com/wekan/wekan/pull/1944/commits/be42b8d4cbdfa547ca019ab2dc9a590a115cc0e2). Also add to [Cards page](REST-API-Cards)
# Add Swimlane to Board
| API URL / Code Link | Requires Admin Auth | HTTP Method |
| :--- | :--- | :--- |
| [/api/boards/:boardId/swimlanes](https://github.com/wekan/wekan/blob/main/models/swimlanes.js#L223) | `yes` | `POST` |
```shell
curl -H "Authorization: Bearer t7iYB86mXoLfP_XsMegxF41oKT7iiA9lDYiKVtXcctl" \
-H "Content-type:application/json" \
-X POST \
http://localhost:3000/api/boards/YRgy7Ku6uLFv2pYwZ/swimlanes \
-d '{ "title": "Swimlane title text" }'
```
## Result example
The new swimlane's ID is returned in the format:
```json
{
"_id": "W9m9YxQKT6zZrKzRW"
}
```
# Delete a swimlane
| API URL / Code Link | Requires Admin Auth | HTTP Method |
| :--- | :--- | :--- |
| [/api/boards/:boardId/swimlanes/:swimlaneId](https://github.com/wekan/wekan/blob/main/models/swimlanes.js#L257) | `yes` | `DELETE` |
```shell
curl -H "Authorization: Bearer t7iYB86mXoLfP_XsMegxF41oKT7iiA9lDYiKVtXcctl" \
-H "Content-type:application/json" \
-X DELETE \
http://localhost:3000/api/boards/YRgy7Ku6uLFv2pYwZ/lists/PgTuf6sFJsaxto5dC/cards/ssrNX9CvXvPxuC5DE
```
## Result example
The swimlane's ID is returned in the format:
```json
{
"_id": "W9m9YxQKT6zZrKzRW"
}
```
# In Wekan code
If you believe that code is the best documentation, be our guest: [models/cards.js](https://github.com/wekan/wekan/blob/main/models/swimlanes.js "Swimlane API code")

335
docs/API/REST-API-User.md Normal file
View file

@ -0,0 +1,335 @@
# Disclaimer
This page tries to be as up to date as possible. If you see something wrong here, feel free to update the page and help other people like you, that greatly depends on our APIs. If you don't feel comfortable doing this kind of changes, please contact us by creating an [issue](https://github.com/wekan/wekan/issues/new).
# User Register
| URL | Requires Auth | HTTP Method |
| :--- | :--- | :--- |
| `/users/register` | `no` | `POST` |
## Payload
| Argument | Example | Required | Description |
| :--- | :--- | :--- | :--- |
| `username` | `myusername` | Required | Your username |
| `password` | `my$up3erP@ssw0rd` | Required | Your password |
| `email` | `my@email.com` | Required | Your email |
* Notes:
* **You will need to provide the `token` for any of the authenticated methods.**
## Example Call - As Form Data
```bash
curl http://localhost:3000/users/register \
-d "username=myusername&password=mypassword&email=my@email.com"
```
## Example Call - As JSON
```bash
curl -H "Content-type:application/json" \
http://localhost:3000/users/register \
-d '{ "username": "myusername", "password": "mypassword", "email": "my@email.com" }'
```
## Result
```json
{
"id": "user id",
"token": "string",
"tokenExpires": "ISO encoded date string"
}
```
## Result example
```json
{
"id": "XQMZgynx9M79qTtQc",
"token": "ExMp2s9ML1JNp_l11sIfINPT3wykZ1SsVwg-cnxKdc8",
"tokenExpires": "2017-12-15T00:47:26.303Z"
}
```
# User Create
| URL | Requires Admin Auth | HTTP Method |
| :--- | :--- | :--- |
| `/api/users` | `yes` | `POST` |
## Payload
| Argument | Example | Required | Description |
| :--- | :--- | :--- | :--- |
| `username` | `myusername` | Required | Your username |
| `password` | `my$up3erP@ssw0rd` | Required | Your password |
| `email` | `my@email.com` | Required | Your email |
* Notes:
* **You will need to provide the `token` for any of the authenticated methods.**
## Example Call - As Form Data
```bash
curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
-X POST \
http://localhost:3000/api/users \
-d "username=myusername&password=mypassword&email=my@email.com"
```
## Example Call - As JSON
```bash
curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
-H "Content-type:application/json" \
-X POST \
http://localhost:3000/api/users \
-d '{ "username": "myusername", "password": "mypassword", "email": "my@email.com" }'
```
## Example of all steps of create user
1) Login
```
curl http://example.com/users/login \
-d "username=YOUR-USERNAME-HERE&password=YOUR-PASSWORD-HERE"
```
As response you get your id and token:
```
"id":"YOUR-ID-HERE","token":"YOUR-TOKEN-HERE","tokenExpires":"2017-12-23T21:07:10.395Z"}
```
2) Create user. Works both when serf-register enabled and disabled.
```
curl -H "Authorization: Bearer YOUR-TOKEN-HERE" \
-H "Content-type:application/json" \
-X POST \
http://example.com/api/users \
-d '{ "username": "tester", "password": "tester", "email": "tester@example.com", "fromAdmin": "true" }'
```
As reply you get new user's id.
```
{"id":"NEW-USER-ID-HERE"}
```
3) You can get user details with your new user's id:
```
curl -H "Authorization: Bearer YOUR-TOKEN-HERE" \
http://example.com/api/users/NEW-USER-ID-HERE
```
## Result
Returns the id of the created user.
```json
{
"_id": "user id"
}
```
## Result example
```json
{
"_id": "EnhMbvxh65Hr7YvtG"
}
```
# User Delete
> IMPORTANT : Should not be used as long as [this bug](https://github.com/wekan/wekan/issues/1289) exists.
| URL | Requires Admin Auth | HTTP Method |
| :--- | :--- | :--- |
| `/api/users/:id` | `yes` | `DELETE` |
## Parameters
| Argument | Example | Required | Description |
| :--- | :--- | :--- | :--- |
| `id` | `BsNr28znDkG8aeo7W` | Required | The id of the user to delete. |
## Example Call
```bash
curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
-X DELETE \
http://localhost:3000/api/users/EnhMbvxh65Hr7YvtG
```
## Example Result
Returns the id of the deleted user.
```json
{
"_id": "EnhMbvxh65Hr7YvtG"
}
```
# User Information
Retrieves information about a user.
| URL | Requires Admin Auth | HTTP Method |
| :--- | :--- | :--- |
| `/api/users/:id` | `yes` | `GET` |
* Notes:
* **You will need to provide the `token` for any of the authenticated methods.**
* **Only the admin user (the first user) can call the REST API.**
## Example Call
```bash
curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
http://localhost:3000/api/users/XQMZgynx9M79qTtQc
```
## Result example
```json
{
"_id": "XQMZgynx9M79qTtQc",
"createdAt": "2017-09-13T06:45:53.127Z",
"services": {
"password": {
"bcrypt": "$2a$10$CRZrpT4x.VpG2FdJxR3rN.9m0NbQb0OPsSPBDAZukggxrskMtWA8."
},
"email": {
"verificationTokens": [
{
"token": "8rzwpq_So2PVYHVSfrcc5f5QZnuV2wEtu7QRQGwOJx8",
"address": "my@email.com",
"when": "2017-09-13T06:45:53.157Z"
}
]
},
"resume": {
"loginTokens": [
{
"when": "2017-09-13T06:45:53.265Z",
"hashedToken": "CY/PWeDa3fAkl+k94+GWzCtpB5nPcVxLzzzjXs4kI3A="
},
{
"when": "2017-09-16T06:06:19.741Z",
"hashedToken": "74MQNXfsgjkItx/gpgPb29Y0MSNAvBrsnSGQmr4YGvQ="
}
]
}
},
"username": "john",
"emails": [
{
"address": "my@email.com",
"verified": false
}
],
"isAdmin": true,
"profile": {}
}
```
# User List
Retrieves the user list.
| URL | Requires Admin Auth | HTTP Method |
| :--- | :--- | :--- |
| `/api/users` | `yes` | `GET` |
* Notes:
* **You will need to provide the `token` for any of the authenticated methods.**
* **Only the admin user (the first user) can call the REST API.**
## Example Call
```bash
curl -H "Authorization: Bearer cwUZ3ZsTaE6ni2R3ppSkYd-KrDvxsLcBIkSVfOCfIkA" \
http://localhost:3000/api/users
```
## Result
```json
[
{
"_id": "user id",
"username": "string"
}
]
```
## Result example
```json
[
{
"_id": "XQMZgynx9M79qTtQc",
"username": "admin"
},
{
"_id": "vy4WYj7k7NBhf3AFc",
"username": "john"
}
]
```
# User Logged-in
Retrieves information about a logged-in user with his auth token.
| URL | Requires Auth | HTTP Method |
| :--- | :--- | :--- |
| `/api/user` | `yes` | `GET` |
* Notes:
* **You will need to provide the `token` for any of the authenticated methods.**
## Example Call
```bash
curl -H "Authorization: Bearer a6DM_gOPRwBdynfXaGBaiiEwTiAuigR_Fj_81QmNpnf" \
http://localhost:3000/api/user
```
## Result example
```json
{
"_id": "vy4WYj7k7NBhf3AFc",
"createdAt": "2017-09-16T05:51:30.339Z",
"username": "john",
"emails": [
{
"address": "me@mail.com",
"verified": false
}
],
"profile": {}
}
```
# Disable a user (the user is not allowed to login and his login tokens are purged)
| URL | Requires Admin Auth | HTTP Method |
| :--- | :--- | :--- |
| `/api/users/:id` | `yes` | `PUT` |
```shell
curl -H "Authorization: Bearer t7iYB86mXoLfP_XsMegxF41oKT7iiA9lDYiKVtXcctl" \
-H "Content-type:application/json" \
-X PUT \
http://localhost:3000/api/users/ztKvBTzCqmyJ77on8 \
-d '{ "action": "disableLogin" }'
```
# Enable a user
| URL | Requires Admin Auth | HTTP Method |
| :--- | :--- | :--- |
| `/api/users/:id` | `yes` | `PUT` |
```shell
curl -H "Authorization: Bearer t7iYB86mXoLfP_XsMegxF41oKT7iiA9lDYiKVtXcctl" \
-H "Content-type:application/json" \
-X PUT \
http://localhost:3000/api/users/ztKvBTzCqmyJ77on8 \
-d '{ "action": "enableLogin" }'
```
# In Wekan code
If you believe that code is the best documentation, be our guest: [models/cards.js](https://github.com/wekan/wekan/blob/main/models/users.js "User API code")

126
docs/API/REST-API.md Normal file
View file

@ -0,0 +1,126 @@
REST API is not complete yet, please add missing functionality with pull requests to devel branch.
If you are in a hurry, you can use these to have more functionality:
* https://restheart.org
* http://vulcanjs.org
For workflows see [If-this-then-that issue](https://github.com/wekan/wekan/issues/1160) than mentions Huginn, Flogo etc.
# Wekan REST API
The REST API allows you to control and extend Wekan with ease.
If you are an end-user and not a dev or a tester, [create an issue](https://github.com/wekan/wekan/issues/new) to request new APIs.
> All API calls in the documentation are made using `curl`. However, you are free to use Java / Python / PHP / Golang / Ruby / Swift / Objective-C / Rust / Scala / C# or any other programming languages.
## Production Security Concerns
When calling a production Wekan server, ensure it is running via HTTPS and has a valid SSL Certificate. The login method requires you to post your username and password in plaintext, which is why we highly suggest only calling the REST login api over HTTPS. Also, few things to note:
* Only call via HTTPS
* Implement a timed authorization token expiration strategy
* Ensure the calling user only has permissions for what they are calling and no more
# Summary
### Authentication
| HTTP Method | Url | Short Description |
| :--- | :--- | :--- |
| `POST` | `/users/login` | [Authenticate with the REST API.](#login) |
### Users
| HTTP Method | Url | Short Description |
| :--- | :--- | :--- |
| `POST` | `/users/register` | [Register a new user.](REST-API-User#user-register) |
| `POST` | `/api/users` | [Create a new user.](REST-API-User#user-create) |
| `PUT` | `/api/users/:id` | [Disable an existing user.](REST-API-User#disable-a-user-the-user-is-not-allowed-to-login-and-his-login-tokens-are-purged) |
| `PUT` | `/api/users/:id` | [Enable an existing user.](REST-API-User#enable-a-user) |
| `PUT` | `/api/users/:id` | [Admin takes the ownership.](REST-API-User#the-admin-takes-the-ownership-of-all-boards-of-the-user-archived-and-not-archived-where-the-user-is-admin-on) |
| `DELETE` | `/api/users/:id` | [Delete an existing user.](REST-API-User#user-delete) ([Warning](https://github.com/wekan/wekan/issues/1289))|
| `GET` | `/api/users/:id` | [Gets a user's information.](REST-API-User#user-information) |
| `GET` | `/api/users` | [All of the users.](REST-API-User#user-list) |
| `GET` | `/api/user` | [Gets a logged-in user.](REST-API-User#user-logged-in) |
### Cards
| HTTP Method | Url | Short Description |
| :--- | :--- | :--- |
| `POST` | `/api/boards/:boardId/lists/:listId/cards` | [Add a card to a list, board, and swimlane.](REST-API-Cards#add-card-to-list-board-swimlane) |
| `PUT` | `/api/boards/:boardId/lists/:fromListId/cards/:cardId` | [Update a card.](REST-API-Cards#update-a-card) |
| `DELETE` | `/api/boards/:boardId/lists/:listId/cards/:cardId` | [Delete a card.](REST-API-Cards#update-a-card) |
---
# Login
| URL | Requires Auth | HTTP Method |
| :--- | :--- | :--- |
| `/users/login` | `no` | `POST` |
## Payload
### Authentication with username
| Argument | Example | Required | Description |
| :--- | :--- | :--- | :--- |
| `username` | `myusername` | Required | Your username |
| `password` | `my$up3erP@ssw0rd` | Required | Your password |
### Authentication with email
| Argument | Example | Required | Description |
| :--- | :--- | :--- | :--- |
| `email` | `my@email.com` | Required | Your email |
| `password` | `my$up3erP@ssw0rd` | Required | Your password |
* Notes:
* **You will need to provide the `token` for any of the authenticated methods.**
## Example Call - As Form Data
DOES NOT WORK ! Please use As JSON example below !
https://github.com/wekan/wekan/issues/4807
```bash
curl http://localhost:3000/users/login \
-d "username=myusername&password=mypassword"
```
```bash
curl http://localhost:3000/users/login \
-d "email=my@email.com&password=mypassword"
```
## Example Call - As JSON
THIS WORKS !! Alternatively, look at api.py example at https://github.com/wekan/wekan
NOTE: Username and password is case sensitive. So type BIG and small letters correctly.
```bash
curl -H "Content-type:application/json" \
http://localhost:3000/users/login \
-d '{ "username": "myusername", "password": "mypassword" }'
```
```bash
curl -H "Content-type:application/json" \
http://localhost:3000/users/login \
-d '{ "email": "my@email.com", "password": "mypassword" }'
```
## Result
```json
{
"id": "user id",
"token": "string",
"tokenExpires": "ISO encoded date string"
}
```
## Result example
```json
{
"id": "XQMZgynx9M79qTtQc",
"token": "ExMp2s9ML1JNp_l11sIfINPT3wykZ1SsVwg-cnxKdc8",
"tokenExpires": "2017-12-15T00:47:26.303Z"
}
```