Roadmap for REST-API features

[mayjs]

@huneau Do you have a roadmap/list of features you plan to add to the REST-API?
I would really like to use this API for multiple projects, but it is still missing some important features to accomplish my goals in these projects.
To be able to start working on them, I would like to help to implement missing endpoints, which is why I was looking for a roadmap.

[huneau]

@mayjs I work for an employer, I have no roadmap no lists of features.
I will maintain bugfix my own code but I don't spend the time to add a feature which is not decided by my product owner.

Up to you to contribute :)

[mayjs]

Okay, I will start to add to the API once I have the time to do it. Here is a list of endpoints and features I'm planning to add to the existing API:

• The current authorization is fine to protect a wekan instance, but to restrictive for my uses. Every user should be allowed to use the API, but an authorization system must be used to restrict the access to certain objects.
• Add GET /api/user/boards, this endpoint should return all boards the user is part of. (Instead of /api/user/boards we could also extend the functionality of GET /api/boards)
• Change GET /api/boards/:id to be usable by users who are able to access it
• Change GET /api/boards/:boardId/lists to be usable by anyone who has access to the board
• Change GET /api/boards/:boardId/lists/:listId/cards to be usable by users who can access the board
• PUT /api/boards/:boardId/lists/:listId/cards/:cardId to update existing cards
• We could create an endpoint to return cards using a filter. (E.g. get all cards that are in the leftmost list or have a certain tag etc.) This feature could allow a client to get all cards to be done by the logged in user without requesting all cards on all boards first. This would require some specification before implementation, to see how the query format should look etc.
• Maybe create special admin endpoints, e.g. to get every board. Some of these endpoints already exist, like POST /api/users.
• Maybe change POST /api/boards and DELETE /api/boards/:id
• Managing labels
• Assigning labels to cards (by extending POST /api/boards/:boardId/lists/:listId/cards)
• Change the remaining admin-only endpoints
• Better error output. Currently HTML gets returned if some parameter was wrong

NOTICE: The checkmarks in this list checkmarks do not necessarily indicate that the feature was already merged into this repository. The features are developed in my fork and will be merged in bigger sets.

If anyone would like to discuss these features or add new ideas to this list, feel free to comment.

[dyindude]

It would be useful to also be able to manage labels for a board via the API, as well as assigning said labels to cards (either on creation or updating existing cards).

[mayjs]

I added label management to the todo list. The assignment to existing cards can be handled in the card updating endpoint.

[huneau]

POST /api/boards/:boardId/lists/:listId/cards could be extended to be able to update existing cards by giving an ID in the posted object. (Or to stay restful, add POST /api/boards/:boardId/lists/:listId/cards/:cardId)

Update = PUT

POST /api/user/cards could be used to return cards using a filter. (E.g. get all cards that are in the leftmost list or have a certain tag etc.) This feature could allow a client to get all cards to be done by the logged in user without requesting all cards on all boards first.

this is GET with parameter /api/users/cards?name=awesomecard

Maybe create special admin endpoints, e.g. to get every board. Some of these endpoints already exist, like POST /api/users

Actually, I have hard coded the filter to get board, just remove my hard coded filter and use parameter filter.

And keep in mind best pratice:
https://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/

[mayjs]

I changed the Update endpoint to PUT.
For the filtering endpoint I was actually planning on some type of JSON query format, which is why I chose POST for it. I also was thinking about more than just simply searching for a name, which is why I did not want to use GET-parameters. But I get your point, we should use a GET-request because this endpoint does not add data to the database. On the other hand I am also not fond of passing JSON via GET.

I will change the text of the filtering feature to a more general description of the feature, I think a specification of what exactly should be possible with this feature is needed before deciding how to implement it.

[mass3y]

How is auth working now? Can't get anything but "Unauthorized" response. Tried basic auth, URL args, Cookies.....nothing appears to work. I am running a local instance, zero changes to Wekan config.

wekan_1    |   Error: Unauthorized [Unauthorized]
wekan_1    |     at Object.Authentication.checkUserId (server/authentication.js:6:21)
wekan_1    |     at models/users.js:541:20
wekan_1    |     at packages/simple_json-routes.js:98:9

API looks great, docs http:https://fusion.github.io/wekanapi/ are sufficient but need to get past this auth problem.
Thanks!

[mayjs]

@mass3y first of all, the page you linked is of a different project which has readonly access. The integrated Wekan API does currently not have documentation like that.
For authentication and authorization, please see #1033. That PR contains a description on how to get tokens to use the API.

[PaulJe]

Thanks for providing the wekan internal API! Great work!!!

A few hints for the others...
I had issues during authentication (does not accept e-mail address passing as username) during login.
(Instead of "username" we can use "email" also for /api/login)

Just in case someone else needs it ...
GET /api/boards -> returns public boards only
GET /api/users/:userid/boards -> returns private boards of a specific user
GET /api/boards/:boardid/lists -> returns the lists from a specific public or private board.

However, it seems "/api/users/:userid/boards" is currently not fully implemented...
In my case... I can pass any string as userid and it returns all my private boards ?!

[mayjs]

Thanks for the information about the bug in GET /api/users/:userid/boards. It is an error in the current implementation, where the wrong parameter is used for getting the boards. Issue #1118 will be used for tracking this issue.
The authentication part we currently use was implemented by @huneau, as far as I know he intended login only via username and not with email address.

[xet7]

Moved to here from #1183

From @Krantz-Man

REST-API: Add card to list using POST request

I noticed that there is an endpoint for what looks to be adding a new card (/api/users/:userid/boards/:boardid/lists/:listid/cards), but I could not find anything for what was required to be sent in the request body. Every time I send the post request, I just get back Internal Server Error.

@mayjs @huneau

Can you duplicate this, is there a bug ? Or is something missing from API ?

[mayjs]

I cannot test this right now, but in theory the endpoint should work. @Krantz-Man you have to be authenticated with an admin account. This is the structure to be used for the post data:

{
  title: "your card title",
  description: "your description",
  authorId: "userid of the author"
}

If one of these parameters is missing, an internal server error will occur.
I will soon have time to modify data modifying endpoints like this one to be usable by non-admin users.

[xet7]

Example:

curl http:https://localhost:3000/users/login -d "username=myloginname&password=mypassword"

[MaZderMind]

Another missing bit: POST /api/boards always creates a public board and there's not way to make it private via the api.
It's not possible to invite people to Boards.

[TNick]

I will be using this and there might be some pull requests.
Please aggregate the wish list for APIs. What's missing right now, what is badly needed?

I will probably start with a test suite.

[Worren]

Unfortunately I am not able to add a new card by using the API.
I get the authorization, i can get the boardlist via GET /api/boards/:ID/lists, but whenever i try to add a new card, an internal server error returns. The user does have admin rights. Is there something missing in my call?
curl -H "Authorization: Bearer TOKEN" -H "Content-type:application/json" -X POST http:https://localhost:8066/api/boards/ID/lists/ID/cards -d '{ "title": "Card title text", "description": "Card description text", "authorId": "ID" }'

Is the problem the missing swimlane id? How do I get a list of the swimlane ids?

[akuckartz]

I would like to see support for JSON-LD. Should I create a separate issue?

[xet7]

@akuckartz

You can keep it here. What is JSON-LD ?

[arradoq]

Unfortunately I am not able to add a new card by using the API.
I get the authorization, i can get the boardlist via GET /api/boards/:ID/lists, but whenever i try to add a new card, an internal server error returns. The user does have admin rights. Is there something missing in my call?
curl -H "Authorization: Bearer TOKEN" -H "Content-type:application/json" -X POST http:https://localhost:8066/api/boards/ID/lists/ID/cards -d '{ "title": "Card title text", "description": "Card description text", "authorId": "ID" }'

Is the problem the missing swimlane id? How do I get a list of the swimlane ids?

I get the same problem, on mine, there are no notification on what i did wrong, I am using windows installation and curl-ing by using git bash. Anyone using windows and get the same problem?

[akuckartz]

@xet7 https://en.m.wikipedia.org/wiki/JSON-LD

[BobCashStory]

Hey we plan to manage account of our user with api since data are update in our main app like name email etc we wanna be able to update the users created in Wekan could we allow post on user only with admin right of course ?

[xet7]

@BobCashStory

Please see this comment how to manage users and roles with Wekan API:
#2412 (comment)

[BobCashStory]

@xet7 thanks i found https://wekan.github.io/api/v2.71/#edit_user but doesn't seem we can update fullname password etc, do we ?

[xet7]

@BobCashStory

It needs checking is that possible, so I added feature request to #2430

[Robert-Lebedeu]

Hi,
I was asked to create a software that, through API requests, would made possible to create cards and checklists for a given board.
I faced some problems, in particular, only admin user had the rights to create those things.
I don't think this should be the correct behavior.
I opened this PR #2854 but I haven't received any response. I found out about this issue and I decided to write this comment hoping that someone would help me to reach my goal.
In my PR basically I re-used some functions to check user role allowing no-admin users to add cards and checklist to boards of which they are one of the members (and have the correct permissions).