Repository navigation
Description
Who is asking. NC-Gantt (https://codeberg.org/fds2610/NC-Gantt) is a project planning
app (Gantt chart) for Nextcloud. Projects, subprojects and tasks can be linked to Deck
boards, lists and cards, so that planning and day-to-day work stay in one place: the
plan hands work over to Deck, and Deck stays the single place where that work is done.
What we do today. Deck has an excellent read channel — since Deck 1.18 the
webhook-compatible CardCreatedEvent / CardUpdatedEvent / CardDeletedEvent (#7910) give
us everything we need to follow changes made in Deck. Thank you for those; this
request is only about the other direction.
For writing we have no supported option, so we call Deck's internal services from a
single adapter class (DeckGateway), fetched from the container at call time so that
our app still loads without Deck: CardService (find, create, update, archive),
AssignmentService::assignUser(), BoardService::find(), StackMapper (find, findAll).
These are not meant as an API, and we treat them accordingly: one adapter class, a
contract test that checks every class, method parameter and entity field we touch
against the installed Deck, and a documented review of stable31…stable35 plus master
before every release. That keeps the risk visible, but it does not remove it — and it
puts work on you too, because any refactoring in these services can silently break
third-party apps you never hear about.
Why the internal services are hard to use correctly
- Signatures move, by design. Between Deck 1.15 and 1.19, CardService::update()
gained $done, $startdate and $color, partly in the middle of the parameter list. We
now call create() and update() with named arguments resolved through reflection,
because a positional call would break on the next release. That is a workaround, not
an integration. - The acting user comes from the session. CardService and PermissionService receive
the user as private ?string $userId at construction time. In a background job or an
occ command there is no session, so we have to set the "volatile active user" before
calling Deck — and hope that is enough for every code path inside Deck. An API that
takes the acting user as a parameter would make this correct by construction. - No partial updates. update() requires title, stackId, type and owner even when we
only want to move a due date. So every write is a read-modify-write over the whole
card, which loses concurrent edits made in Deck between our read and our write —
exactly the thing a planning app that writes dates must not do. (Same pain as API: Updating items should not require all parameters to be set #1578 on
the REST side.) Deck already has OptionalNullableValue for done and color, so the
idea of "field not supplied ≠ field set to null" exists in the code base; we would
like it for all fields.
Why not the REST/OCS API? An app running inside the same server would have to call its
own server over HTTP, with credentials it does not have, losing the acting user's
session and the transaction context. Talk's "create card" goes that way today (#8116);
we would rather not add another one.
What we need
| Operation | Data
|
|--------------------------------|----------------------------------------------------
-------------------------------------------|
| Create a card | title, description, target list (stack), due date,
start date |
| Read a card | id, title, description, stack/board, due date,
start date, done, archived, deleted, assignees |
| Set dates | due date and start date, each independently, "leave
unchanged" distinguishable from "clear" |
| Mark done / undone | —
|
| Assign / unassign a user | card, user id; a clear, catchable error when the
account has no access to the board |
| Archive a card | (we never delete a card that a user might still
need) |
| List the stacks of a board | id, title, order — to offer a target list
|
| Permissions of the acting user | read / edit / manage on a board, so the UI can hide
what the user may not do |
Permissions stay with Deck. We are explicitly not asking for a way around Deck's
permission checks. Deck should keep checking the rights of the acting person on every
call, exactly as it does for its own controllers, and refuse otherwise. Our app also
never shares a board on the user's behalf: if an assignment fails because the account
cannot see the board, we want to catch that and tell the user, not fix it silently.
Suggested shape
- Interfaces in a stable namespace of Deck (for example OCA\Deck\Api*), registered in
the container, versioned with @SInCE tags — the same contract style Nextcloud uses
for OCP, and the same promise the webhook-compatible events already made for reading. - The acting user as an explicit parameter of every call, not read from the session at
construction time, so the API also works in background jobs and occ commands. - Partial updates: a change object or "not supplied" marker per field (Deck's existing
OptionalNullableValue is a good starting point). - Documented exceptions for "not found", "no permission" and "invalid input", so
callers can map them to their own states instead of catching Throwable. - A small surface is fine. The table above would already remove our entire dependency
risk; we would rather have seven stable operations than everything Deck can do.
What this would change for us
Once such an API exists, our adapter would use it from that Deck version on and keep
the current internal calls only as a fallback for older versions — and we would drop
them entirely once those versions are out of support. We are happy to help: reviewing
a draft interface, testing a branch against our integration, or contributing the
implementation if you tell us the shape you would accept.
Activity
[-]Question: what is Deck%s future about?[/-][+]Feature request: a public, stable PHP API so other apps can create and update cards[/+]grnd-alt commentedon Sep 24, 2026
Hey, thanks for coming up with this here. I have different opinions/questions on some parts of the issue.
The first point is mainly a code style issue I think (?), that the signatures change will have to be the case as new features develop etc. Do you request for this to be more organized (not change the order of params e.g.), would be nice if you could elaborate a little on this.
The active user is gotten from server via dependency injection, and I do not prefer giving the acting user as a parameter to every single function, I think we should keep using the dependency injection for that. Deck itself also has commands running outside of userSession context and the boardService for example has a function setUserId, I am open to expanding other classes so that the userId can be set as well.
Same I would like to set single fields only by supplying the cardId and the field to update as well!
fds2610 commentedon Oct 6, 2026
Hi @grnd-alt, thank you very much for taking the time to read this and for the thoughtful reply. I'm well aware that Deck is a mature project with many users, so I really appreciate it.
I had another look at what our integration actually uses, and I think I presented the request too broadly. Let me narrow it down.
On 1: it's about stability, not style. I should have been clearer. New parameters are completely fine. What hurts is that we can't tell which signatures and entity fields are meant to stay, so we have to guard everything ourselves with reflection and a contract test. Nothing needs to be reorganized.
On 2: you are right, and I'd like to withdraw that point. NC-Gantt only ever acts inside the logged-in user's session (no cron, no occ), so the injected user works for us. If background use ever comes up, setUserId as you describe is a perfectly good answer. Please don't change this on our account.
On 3: this is the one that really matters to us. Today, to move a due date we have to call CardService::update() with title, stackId, type, owner, description, order, deletedAt and archived, read beforehand and written back unchanged. If someone edits the card in Deck between our read and our write, we silently overwrite that change. Your suggestion (cardId plus the single field) would solve it completely.
Concretely, our whole write path against Deck is: create a card, set due/start date, assign a user, archive a card. Everything else (find, assignUser, archive, BoardService::find, StackMapper) has been stable for us so far.
So if it helps, here is the smallest version I can imagine, without any new namespace or large API:
// sketch – field not supplied ≠ field set to null public function updateFields(int $cardId, array|CardChanges $changes): Card // e.g. ['duedate' => $date], ['startdate' => null], ['archived' => true]Even just marking a handful of existing methods and the exceptions they throw as stable (@SInCE) would already help a lot. In particular, a distinguishable exception for "user has no access to this board" in assignUser would be great; we currently infer it from BadRequestException.
I'm happy to do the work: I can open a draft PR for the partial update (with tests) so you can judge the shape, or adapt it to whatever direction you prefer. And if you'd rather not take this on right now, that's completely understandable. Thanks again for Deck and for your time.
Felix