[NOMERGE] feat: openapi migration progress #150

ahmed-n-abdeltwab · 2025-07-17T17:01:56Z

🚀 OpenAPI Migration Progress

This PR tracks the ongoing progress of migrating Rocket.Chat API endpoints to the new OpenAPI pattern with AJV validation and improved documentation. It will be continuously updated to reflect completed and remaining work.

✅ Summary

Total endpoints: XX (calculating...)
Migrated so far: 42
Remaining: XX (calculating...)

👥 Team

Ahmed Nasser – Contributor
Matheus Cardoso – Mentor
Guilherme Gazzo – Co-mentor

📢 Team Chat: Join our chat

If you have found my work useful and you’d like to sponsor me, you’re welcome to do so via GitHub Sponsors. Thanks!

🚨 Core API Endpoints

These are 500 endpoints critical for core features and should be migrated first:

Authentication (0 / 9 completed)

Content Management (0 / 11 completed)

Integrations (7 / 13 completed)

Marketplace Apps (0 / 4 completed)

apps/public/{app-id}/incoming
apps/public/{appId}/templateMessage
apps
apps/logs

Messaging (3 / 39 completed)

Omnichannel (0 / 154 completed)

Miscellaneous (0 / 24 completed)

Notifications (0 / 6 completed)

Rooms (0 / 126 completed)

Settings (1 / 47 completed)

Statistics (0 / 15 completed)

User Management (2 / 52 completed)

Let me know if you'd like these grouped, categorized, or documented further.

📝 Secondary API Endpoints

These 2 endpoints are lower priority and can be migrated after core APIs: (calculating...)

Statistics (0 / 1 completed)

statistics.telemetry ⚠️ Blocked – feat: Add OpenAPI Support to Statistics API Rocket.Chat#35692

⛔ Typia generates oneOf when it encounters a union type (|) in the interface.
The issue with oneOf is that it requires exactly one schema to match—similar to XOR logic—so overlapping types fail validation.
To fix this, we need Typia to generate anyOf instead of oneOf.

User Management (0 / 1 completed)

users.getAvatarSuggestion ✏️ Needs Update – feat: Add OpenAPI Support to users.getAvatarSuggestion API Rocket.Chat#36402

Notifications (0 / 1 completed)

push.test ✅ Ready for Review – feat: Add OpenAPI Support to push.test API Rocket.Chat#36882

📌 Important Notes

When migrating endpoints to the new OpenAPI + AJV pattern, keep these points in mind:

No Change in Logic
- The migration should only update the structure, validation, and documentation.
- The core business logic, permissions, and side effects must remain exactly the same
Error Response Codes
- 400 (Bad Request) → Should be included for most endpoints with input validation.
- 401 (Unauthorized) → Add only if the endpoint authRequired: true is included.
- 403 (Forbidden) → Add only if specific permission checks are performed.
Schema Validation
- Use AJV for request/response validation.
- Use Typia-generated $ref schemas where available instead of manually defining large object shapes.
Centralized Error Validators
- Use shared helpers like validateBadRequestErrorResponse instead of hard-coding error schemas.
- This keeps error formats consistent across all endpoints.
Route Definition Style
- Use Route Method Chaining when defining multiple methods (.post(), .get(), etc.).
- This is possible because ExtractRoutesFromAPI automatically groups routes under the same path in the type definitions.
Optional Properties
- If an endpoint doesn’t need permissionsRequired, omit it.
- Always explicitly declare query or body in the route options — even if the endpoint has no parameters, set it to query: undefined or body: undefined.
- Keep configs minimal — only include what’s necessary for that endpoint.
No More rest-typings or Manual Typings
- All request/response schemas are now defined directly inside the route definition file.
- No schema definitions in rest-typings or other manual typing files — everything for an endpoint lives in one place for easier maintenance.
Swagger Documentation
- Confirm that both request and response schemas appear correctly in Swagger UI.
- Check that example values are meaningful and match real data structures.

📖 Example: Migrating from Old Pattern to New Pattern

This example shows how to migrate from the legacy addRoute approach (with manual typings and deprecated validation)
to the new typed API definition pattern using:

API.v1.post() / .get() chaining (so multiple HTTP methods for the same path are merged in typings)
AJV for request & response validation
Typia $ref for shared model schemas
Automatic route typings with ExtractRoutesFromAPI (no more manual duplication)
Predefined error response validators instead of hard-coded schemas

Before – Old Pattern

// Route definition
API.v1.addRoute(
	'baz.foo',
	{
		authRequired: true,
		validateParams: ajv.compile<{ name: string }>({ // ❌ Deprecated
				type: 'object',
				properties: { name: { type: 'string' } },
				required: ['name'],
				additionalProperties: false,
			}),
		permissionsRequired: ['manage-foo'],
	},
	{
		async post() {
			const result = await updateFoo(this.bodyParams);
			return API.v1.success(result);
		},
	},
);

API.v1.addRoute(
	'baz.bar',
	{
		authRequired: true,
		validateParams: ajv.compile<{ name: string }>({ // ❌ Deprecated
				type: 'object',
				properties: { name: { type: 'string' } },
				required: ['name'],
				additionalProperties: false,
			}),
		permissionsRequired: ['manage-bar'],
	},
	{
		async get() {
			return API.v1.success(await getBar(this.queryParams.name));
		},
	},
);

// Manual typings in rest-typings
export type BazEndpoint = {
	POST: (params: FooParams) => FooResponse;
    GET: (params: BarParams) => BarResponse;
};

Problems with the old approach:

No request/response schemas → can't generate Swagger/OpenAPI documentation automatically.
validateParams is deprecated → doesn’t integrate with the new pattern.
Manual typings in rest-typings → easy to forget or let them get out of sync.
Hard-coded error handling → duplicated schemas everywhere.

After – New Pattern

const bazEndpoints = API.v1
	// POST /v1/baz.foo
	.post(
		'baz.foo',
		{
			authRequired: true,
			body: ajv.compile<{ name: string }>({
				type: 'object',
				properties: { name: { type: 'string' } },
				required: ['name'],
				additionalProperties: false,
			}),
			permissionsRequired: ['manage-foo'],
			response: {
				400: validateBadRequestErrorResponse, // Common for validation errors
				// 401: validateUnauthorizedErrorResponse, // Optional: if endpoint used with auth
				// 403: validateForbiddenErrorResponse,   // Optional: if specific permission checks exist
				200: ajv.compile<{ foo: IBaz }>({
					type: 'object',
					properties: {
						foo: { $ref: '#/components/schemas/IBaz' }, // ✅ Typia model reuse
						success: { type: 'boolean', enum: [true] },
					},
					required: ['foo', 'success'],
					additionalProperties: false,
				}),
			},
		},
		async function action() {
			const result = await updateFoo(this.bodyParams);
			return API.v1.success(result);
		},
	)
	// GET /v1/baz.bar
	.get(
		'baz.bar',
		{
			authRequired: true,
			query: ajv.compile<{ name: string }>({
				type: 'object',
				properties: { name: { type: 'string' } },
				required: ['name'],
				additionalProperties: false,
			}),
			permissionsRequired: ['manage-bar'],
			response: {
				400: validateBadRequestErrorResponse,
				// 401: validateUnauthorizedErrorResponse, // Optional
				// 403: validateForbiddenErrorResponse,   // Optional
				200: ajv.compile<{ foo: IBaz }>({
					type: 'object',
					properties: {
						bar: { $ref: '#/components/schemas/IBaz' },
						success: { type: 'boolean', enum: [true] },
					},
					required: ['bar', 'success'],
					additionalProperties: false,
				}),
			},
		},
		async function action() {
			return API.v1.success(await getBar(this.queryParams.name));
		},
	);

// ✅ Automatically generate typings for both GET and POST without duplication
export type Bazpoints = ExtractRoutesFromAPI<typeof bazEndpoints>;

declare module '@rocket.chat/rest-typings' {
    // eslint-disable-next-line @typescript-eslint/naming-convention, @typescript-eslint/no-empty-interface
	interface Endpoints extends BazEndpoints {}
}

Key Improvements in the New Pattern

Single source of truth for typings
ExtractRoutesFromAPI pulls types directly from your post() / get() definitions — no more manual edits in rest-typings.
Strong request validation with AJV
Both body (POST) and query (GET) are validated against JSON schemas.
Strong response validation
Ensures the API always returns objects that match the documented shape.
Reusable schemas with Typia
$ref: '#/components/schemas/IBaz' links to a single IBaz schema used across APIs.
Predefined error validators
validateBadRequestErrorResponse, validateUnauthorizedErrorResponse, validateForbiddenErrorResponse replace repetitive error schemas.
Chaining multiple methods on the same path
Calling .post().get() on the same fooEndpoints ensures both methods are merged into one entry in the generated Endpoints interface.

🧪 Testing Plan

Ensure all migrated endpoints validate request and response schemas using AJV.
Confirm accurate documentation in Swagger UI for each endpoint.
Run integration tests to avoid regressions.

💡 Notes

This PR is for tracking and visibility; implementation PRs will be linked progressively.
Please feel free to suggest changes to prioritization.

CLAassistant · 2025-07-17T17:02:03Z

All committers have signed the CLA.

…ser-management.yaml

refactor: remove the webdav from the integrations

34579b4

ahmed-n-abdeltwab added 10 commits July 29, 2025 19:18

refactor: remove pinMessage endpoint from messaging.yaml

ec09975

refactor: remove oauth-apps.create endpoint from integrations.yaml

e29b515

refactor: remove auth-apps.list endpoint from integrations.yaml

2511f83

refactor: remove aoth-apps.delete endpoint from integration

8484c0a

refactor: remove auth-app.update from integration.yaml

da38710

refactor: remove permissions.list, permissions.update endpoint from u…

310412e

…ser-management.yaml

refactor: remove oauth-apps.get endpoint from integration.yaml

b818278

refactor: remove dm.delete endpoint from messaging.yaml

ab7bd56

refactor: remove e2e.setRoomKeyID endpoint from settings.yaml

fe1a149

refactor: remove unPinMessage endpoint from messaging.yaml

f27016e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[NOMERGE] feat: openapi migration progress #150

[NOMERGE] feat: openapi migration progress #150

Uh oh!

ahmed-n-abdeltwab commented Jul 17, 2025 •

edited

Loading

Uh oh!

CLAassistant commented Jul 17, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

[NOMERGE] feat: openapi migration progress #150

Are you sure you want to change the base?

[NOMERGE] feat: openapi migration progress #150

Uh oh!

Conversation

ahmed-n-abdeltwab commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 OpenAPI Migration Progress

✅ Summary

👥 Team

🚨 Core API Endpoints

📝 Secondary API Endpoints

📌 Important Notes

📖 Example: Migrating from Old Pattern to New Pattern

Before – Old Pattern

After – New Pattern

🧪 Testing Plan

💡 Notes

Uh oh!

CLAassistant commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ahmed-n-abdeltwab commented Jul 17, 2025 •

edited

Loading

CLAassistant commented Jul 17, 2025 •

edited

Loading