[NOMERGE] feat: openapi migration progress#150
[NOMERGE] feat: openapi migration progress#150ahmed-n-abdeltwab wants to merge 24 commits intoRocketChat:mainfrom
Conversation
…ser-management.yaml
|
Hey @ahmed-n-abdeltwab , I'd like to take on the rooms.leave migration. I don't see any open PR for it. Can I go ahead? |
Please go ahead, but mention this PR so I can mark it yours, because this way no one can duplicate the work |
|
@Verifieddanny, once your PR is merged, could you please remove your old API like me? |
|
Yes I will 🫡 |
|
Hi @ahmed-n-abdeltwab , I see there's another PR (#39603) for |
We could merged the two PR together but it's recommended if everyone work on deferent API |
|
Hi @ahmed-n-abdeltwab , I'd like to migrate |
ok |
|
Hi @ahmed-n-abdeltwab, I'd like to claim |
sure, go ahead |
|
Hi @ahmed-n-abdeltwab, I'd like to claim voip/call/{callId}/* for migration. Can I go ahead? |
The Omnichannel APIs is bottom of the list. We should probably migrate the other modules first |
Then can i go for users.create, users.register endpoints? |
ok |
hey @ahmed-n-abdeltwab , I have replied to your questions on my PRs, fyi, thanks a lot for the feedback btw!! |
|
Hi @ahmed-n-abdeltwab , I've opened PRs for the following migrations: |
|
hi @ahmed-n-abdeltwab you have already reviewed pr RocketChat/Rocket.Chat#39625 (comment) and I have implemented your requested changes, so just leaving this here |
|
Hi @ahmed-n-abdeltwab Could you please review them when you get a chance? |
|
Hi @ahmed-n-abdeltwab , I have completed the migration of two endpoints to the typed REST API structure:
Both endpoints are now aligned with the typed REST endpoint pattern used across the codebase. I have resolved the conflicts, and everything looks correct from my side. Whenever you have time, could you please review them? |
no it's not completed yet, you still need to complete the other steps |
@ahmed-n-abdeltwab can you also checkout issue RocketChat/Rocket.Chat#38876 |
Thanks for the feedback. Could you please clarify which remaining steps I should complete for these migrations? So far I have:
Please let me know what additional steps are still missing so I can complete them. |
|
@ahmed-n-abdeltwab can I claim users.delete and users.getUsernameSuggestion?, I see no PRs |
i suggest you should first compete what you have claim, until that you could move to the next API. make sure that's your old PRs are really ready and migrated completely |
read the Important Notes number 7, or take a look at the example
|
like I have commented on what u hv asked on chat.getDeletedMessages and chat.postMessage, I do strongly believe my two PRs other than postMessage are ready to merge, i checked out the ui as well its working as expected |
|
I have completed the migration of two endpoints to the typed REST API structure: Whenever you have time, could you please review them? If any changes needed I will fix it. |
I’ve addressed Note #7 — removed rest-typings and moved all schemas to the route files for both endpoints. Updated PRs:
Please review when you have time. |
OpenAPI Migration Progress
This PR tracks the ongoing progress of migrating
Rocket.Chat APIendpoints to the new OpenAPI pattern with AJV validation and improved documentation. It will be continuously updated to reflect completed and remaining work.✅ Summary
👥 Team
🚨 Core API Endpoints
These are 500 endpoints critical for core features and should be migrated first:
Authentication (1 / 9 completed)
Content Management (4 / 11 completed)
emoji-custom.createchore: Add OpenAPI Support to emoji-custom.create API Rocket.Chat#36523custom-user-status.listchore: Add OpenAPI Support to custom-user-status.list API Rocket.Chat#36916Integrations (15 / 15 completed)
webdav.getMyAccountsfeat: Add OpenAPI Support to Webdav API Rocket.Chat#35884webdav.removeWebdavAccountfeat: Add OpenAPI Support to Webdav API Rocket.Chat#35884oauth-apps.createfeat: Add OpenAPI Support to oauth-apps.create API Rocket.Chat#36507oauth-apps.updatefeat: Add OpenAPI Support to oauth-apps.update API Rocket.Chat#36585oauth-apps.listfeat: Add OpenAPI Support to oauth-apps.list API Rocket.Chat#36586oauth-apps.getfeat: Add OpenAPI Support to oauth-apps.get API Rocket.Chat#36598oauth-apps.deletefeat: Add OpenAPI Support to oauth-apps.delete API Rocket.Chat#36606Marketplace Apps (0 / 4 completed)
Messaging (8 / 39 completed)
chat.pinMessagefeat: Add OpenAPI Support to chat.pinMessage API Rocket.Chat#36020chat.unPinMessagefeat: Add OpenAPI Support to chat.unpinMessage API Rocket.Chat#36668dm.closechore: Add OpenAPI Support to dm.close/im.close API Rocket.Chat#38974dm.deletefeat: Add OpenAPI Support to dm.delete/im.delete API Rocket.Chat#36677Omnichannel (0 / 154 completed)
Miscellaneous (20 / 34 completed)
autotranslate.translateMessagechore: Add OpenAPI support for the Rocket.Chat autotranslate translateMessage API Rocket.Chat#38978commands.getchore: Add OpenAPI Support to commands.get API Rocket.Chat#36953removeInvite/:_idendpoint to chained API pattern with AJV validation Rocket.Chat#39200Notifications (3 / 7 completed)
Rooms (6 / 128 completed)
rooms.leavechore: migrate rooms.leave endpoint to new OpenAPI pattern with AJV validation Rocket.Chat#38957rooms.favoritechore: Add OpenAPI Support to rooms.favorite API Rocket.Chat#35995rooms.muteUserandrooms.unmuteUserendpoints to the new pattern Rocket.Chat#39414rooms.muteUserandrooms.unmuteUserendpoints to the new pattern Rocket.Chat#39414Settings (39 / 55 completed)
e2e.fetchMyKeyschore: Add OpenAPI Support to e2e.fetchMyKeys API Rocket.Chat#36779e2e.getUsersOfRoomWithoutKeychore: Add OpenAPI Support to e2e.getUsersOfRoomWithoutKey API Rocket.Chat#36786e2e.setRoomKeyIDfeat: Add OpenAPI Support to e2e.setRoomKeyID API Rocket.Chat#36716e2e.rejectSuggestedGroupKeychore: Add OpenAPI support for the Rocket.Chat e2e endpoints Rocket.Chat#39219e2e.acceptSuggestedGroupKeychore: Add OpenAPI support for the Rocket.Chat e2e endpoints Rocket.Chat#39219e2e.fetchUsersWaitingForGroupKeychore: Add OpenAPI support for the Rocket.Chat e2e endpoints Rocket.Chat#39219e2e.provideUsersSuggestedGroupKeyschore: Add OpenAPI support for the Rocket.Chat e2e endpoints Rocket.Chat#39219e2e.resetRoomKeychore: Add OpenAPI support for the Rocket.Chat e2e endpoints Rocket.Chat#39219e2e.updateGroupKeychore: Add OpenAPI support for the Rocket.Chat e2e.updateGroupKey endpoints Rocket.Chat#39094Statistics (0 / 15 completed)
User Management (11 / 54 completed)
permissions.listAllfeat: Add OpenAPI Support to Permissions API Rocket.Chat#35985permissions.updatefeat: Add OpenAPI Support to Permissions API Rocket.Chat#35985Let 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)
User Management (1 / 1 completed)
users.getAvatarSuggestionchore: Add OpenAPI Support to users.getAvatarSuggestion API Rocket.Chat#36402Notifications (7 / 7 completed)
push.testchore: 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
Error Response Codes
400(Bad Request) → Should be included for most endpoints with input validation.401(Unauthorized) → Add only if the endpointauthRequired: trueis included.403(Forbidden) → Add only if specific permission checks are performed.Schema Validation
$refschemas where available instead of manually defining large object shapes.Centralized Error Validators
validateBadRequestErrorResponseinstead of hard-coding error schemas.Route Definition Style
.post(),.get(), etc.).ExtractRoutesFromAPIautomatically groups routes under the same path in the type definitions.Optional Properties
permissionsRequired, omit it.No More
rest-typingsor Manual Typingsrest-typingsor other manual typing files — everything for an endpoint lives in one place for easier maintenance.Swagger Documentation
📖 Example: Migrating from Old Pattern to New Pattern
This example shows how to migrate from the legacy
addRouteapproach (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)$reffor shared model schemasExtractRoutesFromAPI(no more manual duplication)Before – Old Pattern
Problems with the old approach:
validateParamsis deprecated → doesn’t integrate with the new pattern.rest-typings→ easy to forget or let them get out of sync.After – New Pattern
Key Improvements in the New Pattern
Single source of truth for typings
ExtractRoutesFromAPIpulls types directly from yourpost()/get()definitions — no more manual edits inrest-typings.Strong request validation with AJV
Both
body(POST) andquery(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,validateForbiddenErrorResponsereplace repetitive error schemas.Chaining multiple methods on the same path
Calling
.post().get()on the samefooEndpointsensures both methods are merged into one entry in the generatedEndpointsinterface.🧪 Testing Plan
💡 Notes