chore: migrate `roles.list` endpoint to new chained API pattern with OpenAPI by NAME-ASHWANIYADAV · Pull Request #39194 · RocketChat/Rocket.Chat

NAME-ASHWANIYADAV · 2026-02-28T17:47:43Z

Proposed changes

Migrates the roles.list REST API endpoint from the legacy API.v1.addRoute pattern to the new chained API.v1.get() pattern with AJV response schema validation and OpenAPI documentation support.

Closes #39193

Endpoints migrated

Endpoint	Method	Old Pattern	New Pattern
`roles.list`	GET	`addRoute`	`.get()`

Architectural changes

Replaced legacy API.v1.addRoute('roles.list', ...) with the new chained API.v1.get('roles.list', ...) method
Added AJV response schema for 200 response using $ref: '#/components/schemas/IRole' for Swagger documentation
Added 401: validateUnauthorizedErrorResponse for unauthorized access handling
Wired up ExtractRoutesFromAPI + declare module for automatic type inference (matching pattern used by e2e.ts, permissions.ts, invites.ts)
Removed manual /v1/roles.list typing from rest-typings RolesEndpoints (now inferred from API registration via module augmentation)
Improved existing roles.getUsersInPublicRoles endpoint with success field, required, additionalProperties: false, and 401 error response

Files changed

apps/meteor/app/api/server/v1/roles.ts — Main migration
packages/rest-typings/src/v1/roles.ts — Removed old manual typing

Related project

This continues the REST API migration effort described in the GSoC 2026 project: Replace old REST API definitions over the new API.

cc @diego-sampaio @ggazzo

Summary by CodeRabbit

Refactor
- Refactored roles.list REST API endpoint to modern implementation pattern, now featuring OpenAPI documentation support for improved API discoverability and developer experience.
- Enhanced error handling mechanisms for unauthorized access requests with clearer response schemas.
- Updated public roles endpoint structure for consistency and maintainability.

…enAPI

dionisio-bot · 2026-02-28T17:47:47Z

Looks like this PR is not ready to merge, because of the following issues:

This PR is missing the 'stat: QA assured' label
This PR is missing the required milestone or project

Please fix the issues and try again

If you have any trouble, please check the PR guidelines

changeset-bot · 2026-02-28T17:47:48Z

🦋 Changeset detected

Latest commit: 62620f3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 41 packages

Name	Type
@rocket.chat/meteor	Patch
@rocket.chat/rest-typings	Patch
@rocket.chat/api-client	Patch
@rocket.chat/core-services	Patch
@rocket.chat/ddp-client	Patch
@rocket.chat/http-router	Patch
@rocket.chat/models	Patch
@rocket.chat/ui-contexts	Patch
@rocket.chat/web-ui-registration	Patch
@rocket.chat/account-service	Patch
@rocket.chat/authorization-service	Patch
@rocket.chat/ddp-streamer	Patch
@rocket.chat/federation-matrix	Patch
@rocket.chat/omnichannel-services	Patch
@rocket.chat/presence	Patch
rocketchat-services	Patch
@rocket.chat/omnichannel-transcript	Patch
@rocket.chat/presence-service	Patch
@rocket.chat/queue-worker	Patch
@rocket.chat/abac	Patch
@rocket.chat/network-broker	Patch
@rocket.chat/omni-core-ee	Patch
@rocket.chat/livechat	Patch
@rocket.chat/mock-providers	Patch
@rocket.chat/cron	Patch
@rocket.chat/instance-status	Patch
@rocket.chat/omni-core	Patch
@rocket.chat/server-fetch	Patch
@rocket.chat/ui-client	Patch
@rocket.chat/media-calls	Patch
@rocket.chat/uikit-playground	Patch
@rocket.chat/fuselage-ui-kit	Patch
@rocket.chat/gazzodown	Patch
@rocket.chat/ui-avatar	Patch
@rocket.chat/ui-video-conf	Patch
@rocket.chat/ui-voip	Patch
@rocket.chat/core-typings	Patch
@rocket.chat/apps	Patch
@rocket.chat/model-typings	Patch
@rocket.chat/license	Patch
@rocket.chat/pdf-worker	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2026-02-28T17:48:09Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3c30636 and 62620f3.

📒 Files selected for processing (3)

.changeset/migrate-roles-list-openapi.md
apps/meteor/app/api/server/v1/roles.ts
packages/rest-typings/src/v1/roles.ts

💤 Files with no reviewable changes (1)

packages/rest-typings/src/v1/roles.ts

📜 Recent review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

GitHub Check: cubic · AI code reviewer

🧰 Additional context used

📓 Path-based instructions (1)

**/*.{ts,tsx,js}

📄 CodeRabbit inference engine (.cursor/rules/playwright.mdc)

**/*.{ts,tsx,js}: Write concise, technical TypeScript/JavaScript with accurate typing in Playwright tests
Avoid code comments in the implementation

Files:

apps/meteor/app/api/server/v1/roles.ts

🧠 Learnings (8)

📓 Common learnings

Learnt from: ahmed-n-abdeltwab
Repo: RocketChat/Rocket.Chat PR: 38974
File: apps/meteor/app/api/server/v1/im.ts:220-221
Timestamp: 2026-02-24T19:09:09.561Z
Learning: In RocketChat/Rocket.Chat OpenAPI migration PRs for apps/meteor/app/api/server/v1 endpoints, maintainers prefer to avoid any logic changes; style-only cleanups (like removing inline comments) may be deferred to follow-ups to keep scope tight.

📚 Learning: 2026-02-24T19:09:09.561Z

Learnt from: ahmed-n-abdeltwab
Repo: RocketChat/Rocket.Chat PR: 38974
File: apps/meteor/app/api/server/v1/im.ts:220-221
Timestamp: 2026-02-24T19:09:09.561Z
Learning: In RocketChat/Rocket.Chat OpenAPI migration PRs for apps/meteor/app/api/server/v1 endpoints, maintainers prefer to avoid any logic changes; style-only cleanups (like removing inline comments) may be deferred to follow-ups to keep scope tight.

Applied to files:

.changeset/migrate-roles-list-openapi.md

📚 Learning: 2026-02-25T20:10:16.987Z

Learnt from: ahmed-n-abdeltwab
Repo: RocketChat/Rocket.Chat PR: 38913
File: packages/ddp-client/src/legacy/types/SDKLegacy.ts:34-34
Timestamp: 2026-02-25T20:10:16.987Z
Learning: In the RocketChat/Rocket.Chat monorepo, packages/ddp-client and apps/meteor do not use TypeScript project references. Module augmentations in apps/meteor (e.g., declare module 'rocket.chat/rest-typings') are not visible when compiling packages/ddp-client in isolation, which is why legacy SDK methods that depend on OperationResult types for OpenAPI-migrated endpoints must remain commented out.

Applied to files:

.changeset/migrate-roles-list-openapi.md
apps/meteor/app/api/server/v1/roles.ts

📚 Learning: 2025-11-04T16:49:19.107Z

Learnt from: ricardogarim
Repo: RocketChat/Rocket.Chat PR: 37377
File: apps/meteor/ee/server/hooks/federation/index.ts:86-88
Timestamp: 2025-11-04T16:49:19.107Z
Learning: In Rocket.Chat's federation system (apps/meteor/ee/server/hooks/federation/), permission checks follow two distinct patterns: (1) User-initiated federation actions (creating rooms, adding users to federated rooms, joining from invites) should throw MeteorError to inform users they lack 'access-federation' permission. (2) Remote server-initiated federation events should silently skip/ignore when users lack permission. The beforeAddUserToRoom hook only executes for local user-initiated actions, so throwing an error there is correct. Remote federation events are handled separately by the federation Matrix package with silent skipping logic.

Applied to files:

apps/meteor/app/api/server/v1/roles.ts

📚 Learning: 2026-02-24T19:09:01.522Z

Learnt from: ahmed-n-abdeltwab
Repo: RocketChat/Rocket.Chat PR: 38974
File: apps/meteor/app/api/server/v1/im.ts:220-221
Timestamp: 2026-02-24T19:09:01.522Z
Learning: In Rocket.Chat OpenAPI migration PRs for endpoints under apps/meteor/app/api/server/v1, avoid introducing logic changes. Only perform scope-tight changes that preserve behavior; style-only cleanups (e.g., removing inline comments) may be deferred to follow-ups to keep the migration PR focused.

Applied to files:

apps/meteor/app/api/server/v1/roles.ts

📚 Learning: 2026-02-23T17:53:06.802Z

Learnt from: ggazzo
Repo: RocketChat/Rocket.Chat PR: 35995
File: apps/meteor/app/api/server/v1/rooms.ts:1107-1112
Timestamp: 2026-02-23T17:53:06.802Z
Learning: During PR reviews that touch endpoint files under apps/meteor/app/api/server/v1, enforce strict scope: if a PR targets a specific endpoint (e.g., rooms.favorite), do not propose changes to unrelated endpoints (e.g., rooms.invite) unless maintainers explicitly request them. Focus feedback on the touched endpoint's behavior, API surface, and related tests; avoid broad cross-endpoint changes in the same PR unless requested.

Applied to files:

apps/meteor/app/api/server/v1/roles.ts

📚 Learning: 2026-02-26T19:25:44.063Z

Learnt from: gabriellsh
Repo: RocketChat/Rocket.Chat PR: 38778
File: packages/ui-voip/src/providers/useMediaSession.ts:192-192
Timestamp: 2026-02-26T19:25:44.063Z
Learning: In the Rocket.Chat repository, do not reference Biome lint rules in code review feedback. Biome is not used even if biome.json exists; only reference Biome rules if there is explicit, project-wide usage documented. For TypeScript files, review lint implications without Biome guidance unless the project enables Biome rules.

Applied to files:

apps/meteor/app/api/server/v1/roles.ts

📚 Learning: 2026-02-26T19:25:44.063Z

Learnt from: gabriellsh
Repo: RocketChat/Rocket.Chat PR: 38778
File: packages/ui-voip/src/providers/useMediaSession.ts:192-192
Timestamp: 2026-02-26T19:25:44.063Z
Learning: In this repository (RocketChat/Rocket.Chat), Biome lint rules are not used even if a biome.json exists. When reviewing TypeScript files (e.g., packages/ui-voip/src/providers/useMediaSession.ts), ensure lint suggestions do not reference Biome-specific rules. Rely on general ESLint/TypeScript lint rules and project conventions instead.

Applied to files:

apps/meteor/app/api/server/v1/roles.ts

🧬 Code graph analysis (1)

apps/meteor/app/api/server/v1/roles.ts (2)

packages/apps/src/AppsEngine.ts (1)

IRole (15-15)

packages/models/src/index.ts (1)

Roles (180-180)

🔇 Additional comments (5)

apps/meteor/app/api/server/v1/roles.ts (4)

4-10: Import update is clean and scoped correctly.

Adding validateUnauthorizedErrorResponse here matches the new response schema usage and keeps the migration focused.

Based on learnings: "In Rocket.Chat OpenAPI migration PRs for endpoints under apps/meteor/app/api/server/v1, avoid introducing logic changes. Only perform scope-tight changes that preserve behavior; style-only cleanups ... may be deferred."

222-255: roles.list migration to chained API + AJV schema looks good.

This preserves handler behavior while adding OpenAPI-ready response validation and inferred route typing.

Based on learnings: "In Rocket.Chat OpenAPI migration PRs for endpoints under apps/meteor/app/api/server/v1, avoid introducing logic changes. Only perform scope-tight changes that preserve behavior..."

256-297: roles.getUsersInPublicRoles schema tightening is a solid improvement.

Adding success + required + additionalProperties: false at the root and explicit 401 schema improves contract clarity without changing endpoint behavior.

251-251: Remove the concern about _updatedAt—it is not part of the IRole schema.

The IRole interface (packages/core-typings/src/IRole.ts) does not include an _updatedAt field, so the projection on line 251 excluding it has no effect and cannot cause schema validation failure. The schema compatibility concern is unfounded.

Note: IRole is also not included in the typia-generated schemas list (packages/core-typings/src/Ajv.ts), which may warrant a separate investigation if the schema reference at line 236 is intended to be validated.

Likely an incorrect or invalid review comment.

.changeset/migrate-roles-list-openapi.md (1)

1-6: Changeset is clear and aligned with the PR scope.

Patch declarations and summary text accurately describe the endpoint migration and typings/OpenAPI impact.

Walkthrough

Migrates the roles.list REST API endpoint from the legacy API.v1.addRoute pattern to the new chained API.v1.get() pattern, adding OpenAPI documentation support and AJV response schema validation. Updates type definitions accordingly.

Changes

Cohort / File(s)	Summary
Changeset Documentation `.changeset/migrate-roles-list-openapi.md`	Adds changeset entry documenting the migration of roles.list endpoint to new chained API pattern with OpenAPI and schema validation support. Marks patch updates for `@rocket.chat/meteor` and `@rocket.chat/rest-typings`.
API Route Implementation `apps/meteor/app/api/server/v1/roles.ts`	Converts roles.list route from `API.v1.addRoute` to chained `API.v1.get()` pattern with response schema `{ roles: IRole[]; success: true }`. Adds 401 error handler with `validateUnauthorizedErrorResponse`. Consolidates roles.getUsersInPublicRoles route into the chain. Imports validateUnauthorizedErrorResponse from rest-typings.
Type Definitions `packages/rest-typings/src/v1/roles.ts`	Removes manual endpoint definition for `'/v1/roles.list'` from RolesEndpoints type, aligning with auto-generated types from new chained API pattern.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Suggested labels

type: chore

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: migrating the roles.list endpoint to the new chained API pattern with OpenAPI support.
Linked Issues check	✅ Passed	The PR successfully implements all coding requirements from issue `#39193`: migrates roles.list to chained API.v1.get() pattern, adds AJV response schema validation, enables OpenAPI documentation, implements type inference via ExtractRoutesFromAPI, and removes manual typings.
Out of Scope Changes check	✅ Passed	All changes are directly related to the roles.list endpoint migration objective. The improvements to roles.getUsersInPublicRoles response schema align with modernizing the API routes as part of the broader migration effort.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

cubic-dev-ai

No issues found across 3 files

chore: migrate roles.list endpoint to new chained API pattern with Op…

62620f3

…enAPI

NAME-ASHWANIYADAV requested review from a team as code owners February 28, 2026 17:47

coderabbitai bot added the type: chore label Feb 28, 2026

cubic-dev-ai bot reviewed Feb 28, 2026

View reviewed changes

ahmed-n-abdeltwab mentioned this pull request Mar 1, 2026

[NOMERGE] feat: openapi migration progress RocketChat/Rocket.Chat-Open-API#150

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: migrate `roles.list` endpoint to new chained API pattern with OpenAPI#39194

chore: migrate `roles.list` endpoint to new chained API pattern with OpenAPI#39194
NAME-ASHWANIYADAV wants to merge 1 commit intoRocketChat:developfrom
NAME-ASHWANIYADAV:chore/migrate-roles-list-openapi

NAME-ASHWANIYADAV commented Feb 28, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

dionisio-bot bot commented Feb 28, 2026

Uh oh!

changeset-bot bot commented Feb 28, 2026

Uh oh!

coderabbitai bot commented Feb 28, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

NAME-ASHWANIYADAV commented Feb 28, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Endpoints migrated

Architectural changes

Files changed

Related project

Summary by CodeRabbit

Uh oh!

dionisio-bot bot commented Feb 28, 2026

Uh oh!

changeset-bot bot commented Feb 28, 2026

🦋 Changeset detected

Uh oh!

coderabbitai bot commented Feb 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Suggested labels

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

NAME-ASHWANIYADAV commented Feb 28, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Feb 28, 2026 •

edited

Loading