The docs tree is laid out like the menus - a menu path is a docs path. Admin Panel / Settings follows the new structure: Visibility.md is Appearance.md, with new Features.md, Feature-Profiles.md, Security.md, Activities-and-Notifications.md and Delete.md; the section indexes, Admin-Panel.md, Admin-Panel-URLs.md (with the moved-pane redirects) and Validation.md follow the live menus, and Who-Sees-What.md explains in one place which layer decides what is shown and what is allowed. Pages are added for the menu entries that had none, each written from the code: every Admin Panel / Problems pane, the member menu, the board header, Board Settings, the All Boards left menu, and the list, swimlane and card menus. Older links to the moved panes are updated across docs/. TODO.md records what documenting the menus found: Edit Profile does not save a username for non-admins, the Support page's signed-out case is unreachable, Create board from this card is hidden from members who can edit the card, All Boards Settings is unreachable, and the Share template targets live in browser storage. Thanks to xet7 !
4.5 KiB
Optional APIs: Trello, Jira, GitHub and Gitea compatible
Admin Panel → Settings → Features → Optional APIs turns on REST APIs in the shape of other trackers' APIs (#4930). An app or script written for Trello, Jira, GitHub or Gitea can then use this WeKan as its backend: what it saves is stored in WeKan's database, on WeKan boards, and is seen in WeKan like any other change.
| Tick | Server address for the client | Signs in with |
|---|---|---|
| Trello-compatible API | https://<wekan>/api/compat/trello (paths /1/...) |
?token=<WeKan token> (?key= is ignored), or Authorization: Bearer / OAuth oauth_token="..." |
| Jira-compatible API | https://<wekan>/api/compat/jira (paths /rest/api/2/...) |
Basic authentication with the WeKan token as the password (any user name), or Bearer |
| GitHub-compatible API | https://<wekan>/api/compat/github |
Authorization: token <WeKan token> or Bearer |
| Gitea-compatible API | https://<wekan>/api/compat/gitea/api/v1 |
Authorization: token <WeKan token>, Bearer, or ?token= |
The token is a WeKan API token: the token from POST /users/login, as in the
REST API.
What they may do: exactly what the person may do
None of these APIs has rights of its own. Each one is a translator: a request in Trello's, Jira's, GitHub's or Gitea's shape becomes the matching request to WeKan's own REST API, made with the caller's own token, and WeKan's answer is turned into the other tracker's JSON. So:
- a client sees only the boards its person may see, and writes only where that person may write: board roles, read-only and comment-only members, assigned-only members, list permissions and every other WeKan permission apply unchanged;
- whatever WeKan's REST API refuses, these APIs refuse;
- WeKan's REST API must be on (
WITH_API=true): with it off, every optional API is off too; - an API that is not ticked answers 404, as if it did not exist.
tests/optionalApis.test.cjs fails if any file of server/compatApi/ writes
to a collection, calls a method, or makes a request anywhere except WeKan's
own REST API on the loopback address.
What maps to what
| Trello | Jira | GitHub, Gitea | |
|---|---|---|---|
| Board | board | project (key = the board key) | repository owner/<board key or id> |
| List | list | status; a transition moves the card | the open / closed list |
| Card | card | issue KEY-7 |
issue #7, open or closed as in Version Control |
| Labels | labels and idLabels |
labels |
labels; a label with a due date is a milestone |
| Comments | commentCard actions |
/issue/{key}/comment |
/issues/{n}/comments |
| Checklists | checklists | - | - |
| Delete | archives the card (restorable) | archives the issue | - |
The endpoints:
- Trello:
members/meand itsboards;boards/{id}, itslists,cards,labelsandmembers;POST boards/{id}/labels;lists/{id}/cards(with?idBoard=),POST listsandPUT lists/{id};GET,POST,PUTandDELETE cards/{id};cards/{id}/actionsandPOST cards/{id}/actions/comments;POSTandDELETE cards/{id}/idLabels;cards/{id}/checklistsandPOST checklists. - Jira:
myself;projectandproject/{key}with itsstatuses;searchby GET or POST with simple JQL (project,status,assignee = currentUser(),text ~,key,AND,ORDER BY created|updated|key);GET,POST,PUTandDELETE issue/{key};issue/{key}/comment;issue/{key}/transitions. JQL WeKan does not answer is an error, not a different answer. - GitHub and Gitea:
user,user/repos;repos/{owner}/{repo}; itsissues(withstate,labels,page,per_page, andLinkandX-Total-Countheaders),POSTan issue,GETandPATCH issues/{n}(title, body, state, labels),issues/{n}/comments,labelsandmilestones. A synced issue is closed in its own tracker.
Files
| File | |
|---|---|
models/lib/optionalApis.js |
The catalog, the switch and each client's way of sending the token |
models/lib/trelloCompatApi.js, jiraCompatApi.js, githubCompatApi.js |
The shapes, both ways. No Meteor code |
server/compatApi/core.js |
The switch, and the calls to WeKan's REST API as the caller |
server/compatApi/trello.js, jira.js, githubLike.js |
The routes |
tests/optionalApis.test.cjs, server/lib/tests/compatApi.tests.js |
The tests; the second over real HTTP |