[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 🫡 |
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. |
|
Hey @CodeMatrix1, I wanted to let you know that your previous two PRs (RocketChat/Rocket.Chat#39609 and RocketChat/Rocket.Chat#39602) are still incomplete. You’re missing the steps I previously mentioned in the group chat https://open.rocket.chat/channel/idea-Replace-old-REST-API-definitions-over-the-new-API?msg=em7y5dW3uQkEKvCqE . Opening new PRs before the old ones are finished isn't a good idea; You need to focus on completing those two first. Once they're finished, I can assign the users.delete and users.getUsernameSuggestion APIs to you as you requested |
I am very sorry, I see this makes for a bad impression, I did'nt mean to break any protocol, just thought my PRs were ready and based on what you said earlier I thought I could work on the other two, I will check what went wrong and fix it by tonight |
|
hey again, I am very confused on what is not right, here is what i did for
The main issue seems to might be around the response format. I kept I’m confused what the intended workaround here is — should I make a
I didn’t encounter any issues, tests and bot checks had passed. I hadnt seen any requested changes. I am very confused on what I have missed, can you point me out the right direction by firther commenting on my PRs? Thanks in advance! |
|
Hey @ahmed-n-abdeltwab a few days ago I claimed |
|
Hey @ahmed-n-abdeltwab , I'd like to take on the |
|
@ahmed-n-abdeltwab @ggazzo @cardoso Hi! I've raised a PR #39802 migrating the Could you please review it at your convenience? Also, if you could update the tracking PR description to mark these endpoints as taken/in-progress, that would help avoid any duplication. Thank you! |
|
Hi @ahmed-n-abdeltwab, I'd like to take on the migration of the following two endpoints as well:
Could you please assign these to me whenever you will have free time and update the tracking PR description accordingly |
|
@ahmed-n-abdeltwab @ggazzo @cardoso Hi! I've raised a PR RocketChat/Rocket.Chat#39819 migrating the livechat/agent.info/:rid/:token (GET) and livechat/agent.next/:token (GET) endpoints to the OpenAPI chained API pattern. Could you please review it at your convenience? Also, if you could update the tracking PR description to mark these endpoints as taken/in-progress, that would help avoid any duplication. Thank you! |
|
@ahmed-n-abdeltwab a gentle reminder, I had made the requested changes on chat.getDeletedMessages and chat.search has been stale (so assuming it has no issues), both seem perfect to merge, very simple PRs hope you can review and approve them for merge |
|
Sir @ggazzo , @cardoso , @ahmed-n-abdeltwab
will be opening PRs for these shortly. Could you please exclude these from any upcoming batch migrations? Thanks |
|
Updated the migration progress based on Gazzo's PRs: |
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 / 10 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 / 40 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 / 35 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#35995Settings (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