Skip to content

feat(api): pages and widgets on api/2 - #3133

Open
rubenvdlinde wants to merge 16 commits into
feat/noid/grid-widget-lifecyclefrom
feat/noid/grid-pages-api
Open

rubenvdlinde wants to merge 16 commits into
feat/noid/grid-widget-lifecyclefrom
feat/noid/grid-pages-api

Conversation

@rubenvdlinde

@rubenvdlinde rubenvdlinde commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Part of #3099, on top of #3132 (widget lifecycle). This adds the five endpoints from #3100. They're routed with #[ApiRoute] on the controller, like the newer public endpoints, so routes.php doesn't change.

Size: 4027 lines: 763 code, 530 tests, and 2734 generated OpenAPI (openapi.json and openapi.ts) in separate commits you can skip.

Endpoint What it does Who may
GET /api/2/contexts/{contextId}/pages/{pageId} A page with its widgets Read access to the application
GET /api/2/contexts/{contextId}/pages/{slug} The same, by the page's slug Read access to the application
POST /api/2/contexts/{contextId}/pages Add a grid page (title, icon, description, slug), through createGridPage() Manage access
PATCH /api/2/contexts/{contextId}/pages/{pageId} Change the page, its widgets, or both Manage access
DELETE /api/2/contexts/{contextId}/pages/{pageId} Delete a page other than the start page Manage access
GET /api/2/widget-types The widget types and their settings schemas Any logged-in user
  • Validation. Every widget is read by GridWidgetTypes::readWidget(), the same reader the imports use, and its settings are checked against its type's schema. Unknown settings are dropped and missing ones get their default. Settings are stored as text. A widget id that belongs to another page gives a 400.
  • Data widgets. A data widget shows a table or view that's already in its application: its source is {nodeRelId} of that application. Anything else is refused with a 400, with the same message whether the table doesn't exist or just isn't in the application.
  • Slugs. POST takes one. Leave it out and the page gets page_<id>. An invalid one, or one already used in the application, gives a 400, and so does a PATCH that changes it. The slug is a readable address for reads only; every change goes by page id.
  • Titles. A grid page needs a title of 1 to 200 characters, and a title of only blanks, including no-break and zero width spaces, doesn't count. The start page may have none: an empty title gives it back its default name.
  • Icons must be a known icon name; anything else gives a 400.
  • The start page holds widgets like a grid page, but can't be deleted (400).
  • Limits. At most 100 widgets per page. Adding and deleting pages is limited to 20 a minute per user, changing a page to 60.
  • Versions. Every page has a version, returned with it. A save of the widgets sends the version it was edited from; when another save raised it since, the answer is a 409, so two editors no longer undo each other. A save, a page delete and removing a table or view from the application first lock the application (in ascending id when there are several), so they run one after the other. This closes the races and deadlocks Andy and blizzz found.
  • Responses come from what was written, and a save returns the version it stored; a change doesn't load the application again.
  • Permissions are checked by the controller's RequirePermission, as for the other endpoints. Someone outside the application gets a 404, so outsiders can't tell whether an application exists. Reading needs only read access, which every member has, so reading a page has no 403. The service checks that a page belongs to the application in the URL.

OpenAPI and the TypeScript types are regenerated, in a separate commit.

Saving a page never changes what's in the application, so it can't give the application's sharees access to another table. To show a table that isn't in the application yet, add it to the application first.

How it was tested

After the reviews by Arthur and Andy, on Nextcloud 34 with PostgreSQL:

  • PageServiceTest: reads by id and by name, a page of another application not found, create with an automatic or given slug and a taken slug, blank and invisible titles refused, the start page losing its title again, a save with widgets answering with what it stored, a save without a version refused, a stale version a 409, a page deleted in the meantime a 404, invalid widgets refused before any write (data provider), and deletes
  • ContextPageControllerTest: every endpoint, and 400, 404 and 409; the widget types answer {} for a type without settings
  • WidgetServiceTest, GridWidgetTypesTest and TextHelperTest
  • the full unit suite on this branch: 583 tests
  • psalm and php-cs-fixer, clean; OpenAPI regenerated and in step with the code

By hand on a test instance (Nextcloud 34, PostgreSQL), through the API, 29 checks, all as expected:

  • add a grid page (its title is trimmed, version 0); a taken slug and a title of only no-break and zero width spaces give a 400
  • read the page by id and by slug
  • save widgets without a version: 400; with the current version: 200, answering with the stored widgets and version 1; again from version 0: 409, and the page keeps its widgets
  • a data widget on a table outside the application: 400
  • the start page takes widgets, gets a title, and an empty title gives it back its default name; a grid page can't lose its title
  • the widget types answer {} for the data type, and the page in XML keeps its widget settings
  • a reader reads the page and gets a 403 on change and delete; someone outside the application gets a 404 on read, change and delete
  • deleting the start page gives a 400; deleting a grid page answers with its widgets, leaves no widget rows behind, and the page is gone afterwards

In the browser, with the frontend of #3215: while a page was open in edit mode, another save went through the API. Saving in the browser then showed "Someone else saved this page in the meantime. Reload it to see their changes, then make yours again.", the editor stayed open, and the other save was kept.

🖼️ Screenshots

Backend only, no UI changes. The frontend follows in separate pull requests; #3215 sends the page version.

🏁 Checklist

  • ⛑️ Tests (unit and/or integration) are included or not needed
  • 🔙 Backport requests are created or not needed: /backport to stableX.X
  • 📅 Milestone is set
  • 🌸 PR title is meaningful (if it should be in the changelog: is it meaningful to users?)

🤖 AI (if applicable)

  • The content of this PR was partly or fully generated using AI

Comment thread appinfo/routes.php Resolved
@rubenvdlinde
rubenvdlinde force-pushed the feat/noid/grid-pages-api branch from daeab7e to a812d77 Compare October 24, 2026 08:09
@rubenvdlinde
rubenvdlinde force-pushed the feat/noid/grid-pages-api branch from a812d77 to e241b46 Compare October 26, 2026 09:24
@rubenvdlinde
rubenvdlinde marked this pull request as ready for review October 26, 2026 09:25
Comment thread lib/Service/PageService.php Resolved
Comment thread lib/Service/PageService.php Resolved
#[NoAdminRequired]
#[RequirePermission(permission: Application::PERMISSION_READ, typeParam: 'context', idParam: 'contextId')]
#[ApiRoute(verb: 'GET', url: '/api/2/contexts/{contextId}/pages/{technicalName}', requirements: ['contextId' => '\d+', 'technicalName' => '[a-z][a-z0-9_]*'])]
public function showByTechnicalName(int $contextId, string $technicalName): DataResponse {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to become slug

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done. Pages now have a slug everywhere: the column, the API, the route GET /pages/{slug} and the export. The slug is set when the page is added, page_<id> if none is given, and never changes afterwards: a PATCH with a different slug gets a 400, sending the current one is fine. Columns and views keep their technical name, that is a separate thing.

cc @blizzz

#[UserRateLimit(limit: 20, period: 60)]
#[RequirePermission(permission: Application::PERMISSION_MANAGE, typeParam: 'context', idParam: 'contextId')]
#[ApiRoute(verb: 'POST', url: '/api/2/contexts/{contextId}/pages', requirements: ['contextId' => '\d+'])]
public function create(int $contextId, string $title, ?string $technicalName = null, ?string $icon = null, ?string $description = null): DataResponse {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

another slug todo (there are more in this PR, I won't mention the others to avoid useless clutter)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

btw, does the naming fit? create() is broad, the doc speaks of a grid page only.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All of them are renamed, here and in the PRs on top of this one, including the frontend, which now asks for a slug only when a page is added.

cc @blizzz

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair point, it only ever adds a grid page. It is now createGridPage() in the controller and the service. The route stays POST /pages.

cc @blizzz

Comment thread lib/Service/PageService.php Resolved
Comment thread lib/Service/PageService.php Resolved

@blizzz blizzz left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The adaption to slug is open as well as Andy's findings.

@rubenvdlinde
rubenvdlinde force-pushed the feat/noid/grid-pages-api branch from e835e69 to e5184de Compare November 20, 2026 10:52
Read, add, change and delete grid pages with their widgets, and list
the widget types with their settings schemas. Reading needs read
access to the application, changes need manage access. Page creation
is limited to 20 a minute per user.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
- every page has a version that each save raises as its first write; a save of the
  widgets names the version it was edited from and gets a 409 when another save
  raised it since, so two editors no longer undo each other without a word
- raising the version locks the page, so a save and a delete of the same page run
  one after the other, and adding a page locks its application against a delete
- create, update and delete answer from what they wrote instead of loading the
  application again; reads look up the page itself
- the controller's permission checks are the only ones, as for the other endpoints
- the start page accepts widgets from the start and can lose its title again; the
  delete rule names the start page
- titles and descriptions follow TextHelper, so a title of invisible spaces is refused
- widget settings are stored as text, not as a JSON column, and come back as an array,
  or as {} when empty, so XML keeps them and JSON shows an object
- the widget types answer {} for a type without settings
- the widgets parameter has a named shape in the OpenAPI spec
- deleting a page is rate limited like the other changes
- the database error stub moves here from the data model

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…ector asks

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…ge is added

One lock for the application row, which also takes the write lock first on
SQLite.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Page update() and delete() now take the application lock before they
raise the page version, as create() already did. Every writer then
locks application, page and relations in that order, so a save can no
longer leave widgets behind after a concurrent delete of the
application, and the two cannot deadlock.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…version

Once the version check of a save passed, a widget id that is not on the
page, or a source that is not part of the application, cannot come from
another save, so it is a 400 that names it instead of a 409. The version
in the answer is read on the locked page row inside the transaction, so
a save without a version no longer answers with a stale one.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…s them

Deleting a table or view, or removing one from an application, locks the
rows of the applications that hold it before it touches widgets, page
contents or node relations, in ascending id order. A page save and an
application delete take the application first too, so they wait for each
other instead of deadlocking.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…Page

A page takes its slug when it is added and keeps it: a save that names
another slug is refused with 400, the current slug is accepted. The create
endpoint and service method are named createGridPage, as they add a grid
page only; the route stays POST /pages.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
@rubenvdlinde
rubenvdlinde force-pushed the feat/noid/grid-pages-api branch from e5184de to 1ae1875 Compare November 21, 2026 10:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants