Repository navigation
Conversation
grnd-alt
force-pushed
the
chore/update-API-docs
branch
from
September 24, 2026 13:14
2327c85 to
6db4271
Compare
There was a problem hiding this comment.
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Copilot review overview
Review effort: Lite
Findings: 4
Open (6)
/ocs/v2.php/apps/deck/api/v1.0/, but the tables list routes… · New/ocs/v2.php/apps/deck/api/v1.0/, but the tables list routes… · NewPUT /cards/{cardId}, the parameter list usesid: intbut the route placeholder is… · New## Commentssection introduced earlier in this diff (around line ~1222). This… · New
What changed in this PR
Updates the Deck REST API documentation to clarify that OCS is the preferred API surface and to document OCS endpoint parameters/response types more explicitly.
Changes:
- Added “API selection” guidance and clarified preferred (OCS) vs legacy base URLs.
- Reworked the OCS API section to describe the standard OCS response envelope and summarize key endpoint groups (boards/stacks/cards/attachments/config/etc.) in tables.
- Updated config endpoint documentation to reflect the newer route shape and key conventions.
| File | Description |
|---|---|
| docs/API.md | Expands and restructures API docs to emphasize OCS usage and document endpoint parameters/response types. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Member
|
assisted-by-trailer applicable? |
Assisted-by: GitHub Copilot:MAI-Code-1.1-Flash Signed-off-by: grnd-alt <git@belakkaf.net>
grnd-alt
force-pushed
the
chore/update-API-docs
branch
from
September 24, 2026 15:07
6db4271 to
016bc66
Compare
blizzz
requested changes
Oct 9, 2026
blizzz
left a comment
blizzz
left a comment
Member
There was a problem hiding this comment.
My Claude also complains 😅 :
Sloppiness (AI-generated, and it shows)
- The "API selection" section says the same thing twice in a row, then a third time under # OCS API.
- The closing paragraph ("The config endpoints are already summarized above… exactly as implemented in ConfigController and ConfigService") is filler, and it points users at internal class names.
- Capitalisation in the Notes bullets is inconsistent ("comments support…", "the session endpoint…").
- Per your docs rule: the new lines 19–20 add more nextcloud.local URLs. They should be nextcloud.example.com. Line 81 and older examples have the same problem, which is pre-existing.
| | Method | Route | Parameters | Response | | ||
| | --- | --- | --- | --- | | ||
| | POST | `/cards` | `title: string`, `stackId: int`, `boardId?: int`, `type?: string` (`plain` by default), `owner?: string`, `order?: int` (`999` by default), `description?: string`, `duedate?: mixed`, `startdate?: mixed`, `labels?: array`, `users?: array`, `color?: string` | `Card` | | ||
| | PUT | `/cards/{cardId}` | `cardId: int`, `title: string`, `stackId: int`, `type: string`, `order: int`, `description: string`, `duedate`, `deletedAt`, `boardId?: int`, `owner?: string\|array`, `archived?: mixed`, `startdate?: mixed` | `Card` | |
Member
There was a problem hiding this comment.
in routes, the URL parameter is indeed called cardId, but in the contoller method the parameter is plainly id. Somerthing's afoot there.
| | GET | `/board/{boardId}` | `boardId: int` | `Board` or federated board payload | | ||
| | POST | `/boards` | `title: string`, `color: string` | `Board` | | ||
| | POST | `/boards/team` | `title: string`, `teamId: string`, `color?: string` | `Board` | | ||
| | POST | `/boards/{boardId}/acl` | `boardId: int`, `type: int`, `participant: string`, `permissionEdit: bool`, `permissionShare: bool`, `permissionManage: bool`, `remote?: string` | ACL object | |
Member
There was a problem hiding this comment.
shouldn't remote? be dropped here?
| - Prefer the OCS API at `/ocs/v2.php/apps/deck/api/v1.0/` for all integrations and newly written clients. This is the canonical API used by the Deck web UI and the server-side access points in the app code. | ||
| - The legacy app API at `/index.php/apps/deck/api/v1.0/` still exists for backwards compatibility and is kept available, but it is not the recommended integration path for new projects. | ||
|
|
||
| Use the OCS routes for all new integrations. The legacy `/index.php/apps/deck/api/v1.0/` endpoints still work for backwards compatibility, but they are not the preferred API contract for clients. |
Member
There was a problem hiding this comment.
These actions might not be possible through OCS:
- Board: update (rename, colour), delete, archive, clone. ACL update and delete are missing too. BoardOcsController::updateAcl() exists, but no route points to it, so it's dead code.
- Labels: create, update, delete. Assigning existing labels to cards works.
- Stack: update or rename. Create, reorder, delete and done are available.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.