refactor: migrate instances.get endpoint to new chained API pattern

smirk-dev · smirk-dev · commit 6d1e6dc9667d · 2026-02-21T16:03:32.000Z
Migrates the instances.get REST API endpoint from the legacy API.v1.addRoute() pattern to the new chained .get() pattern with: - Typed response schemas for OpenAPI spec generation - Standardized error response validators (401, 403) - Named action function instead of anonymous method Part of #38876
diff --git a/.changeset/refactor-instances-api-chained-pattern.md b/.changeset/refactor-instances-api-chained-pattern.md
@@ -0,0 +1,5 @@
+---
+'@rocket.chat/meteor': patch
+---
+
+refactor: Migrate `instances.get` API endpoint to new chained pattern with response schemas
diff --git a/apps/meteor/app/api/server/v1/instances.ts b/apps/meteor/app/api/server/v1/instances.ts
@@ -1,4 +1,9 @@
 import { InstanceStatus } from '@rocket.chat/models';
+import {
+	ajv,
+	validateUnauthorizedErrorResponse,
+	validateForbiddenErrorResponse,
+} from '@rocket.chat/rest-typings';
 
 import { isRunningMs } from '../../../../server/lib/isRunningMs';
 import { API } from '../api';
@@ -12,33 +17,81 @@ const getConnections = (() => {
 	return () => getInstanceList();
 })();
 
-API.v1.addRoute(
+API.v1.get(
 	'instances.get',
-	{ authRequired: true, permissionsRequired: ['view-statistics'] },
 	{
-		async get() {
-			const instanceRecords = await InstanceStatus.find().toArray();
-
-			const connections = await getConnections();
-
-			const result = instanceRecords.map((instanceRecord) => {
-				const connection = connections.find((c) => c.id === instanceRecord._id);
-
-				return {
-					address: connection?.ipList[0],
+		authRequired: true,
+		permissionsRequired: ['view-statistics'],
+		response: {
+			200: ajv.compile<{
+				instances: {
+					address?: string;
 					currentStatus: {
-						connected: connection?.available || false,
-						lastHeartbeatTime: connection?.lastHeartbeatTime,
-						local: connection?.local,
+						connected: boolean;
+						lastHeartbeatTime?: number;
+						local?: boolean;
+					};
+					instanceRecord: object;
+					broadcastAuth: boolean;
+				}[];
+			}>({
+				type: 'object',
+				properties: {
+					instances: {
+						type: 'array',
+						items: {
+							type: 'object',
+							properties: {
+								address: { type: 'string', nullable: true },
+								currentStatus: {
+									type: 'object',
+									properties: {
+										connected: { type: 'boolean' },
+										lastHeartbeatTime: { type: 'number', nullable: true },
+										local: { type: 'boolean', nullable: true },
+									},
+									required: ['connected'],
+								},
+								instanceRecord: { type: 'object' },
+								broadcastAuth: { type: 'boolean' },
+							},
+							required: ['currentStatus', 'broadcastAuth'],
+						},
 					},
-					instanceRecord,
-					broadcastAuth: true,
-				};
-			});
-
-			return API.v1.success({
-				instances: result,
-			});
+					success: {
+						type: 'boolean',
+						enum: [true],
+					},
+				},
+				required: ['instances', 'success'],
+				additionalProperties: false,
+			}),
+			401: validateUnauthorizedErrorResponse,
+			403: validateForbiddenErrorResponse,
 		},
 	},
+	async function action() {
+		const instanceRecords = await InstanceStatus.find().toArray();
+
+		const connections = await getConnections();
+
+		const result = instanceRecords.map((instanceRecord) => {
+			const connection = connections.find((c) => c.id === instanceRecord._id);
+
+			return {
+				address: connection?.ipList[0],
+				currentStatus: {
+					connected: connection?.available || false,
+					lastHeartbeatTime: connection?.lastHeartbeatTime,
+					local: connection?.local,
+				},
+				instanceRecord,
+				broadcastAuth: true,
+			};
+		});
+
+		return API.v1.success({
+			instances: result,
+		});
+	},
 );

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@rocket.chat/meteor': patch
 +---
++
 +refactor: Migrate `instances.get` API endpoint to new chained pattern with response schemas