Skip to content

feat: Add OpenAPI Support to integrations.history API #36471

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ahmed-n-abdeltwab wants to merge 7 commits into
base: develop
Choose a base branch
from
Draft

feat: Add OpenAPI Support to integrations.history API #36471

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ee8f17b
feat: convert integrations.history api to the new pattern
ahmed-n-abdeltwab Jul 17, 2025
814c6b2
refactor: remove the old code schema for the integrations History
ahmed-n-abdeltwab Jul 17, 2025
1ba0b46
Create red-squids-develop.md
ahmed-n-abdeltwab Jul 18, 2025
5bcf480
refactor: add 403 json schema
ahmed-n-abdeltwab Jul 19, 2025
fce0724
Merge branch 'develop' into feat/openapi-integrations-history
ahmed-n-abdeltwab Jul 19, 2025
9943595
Merge branch 'develop' into feat/openapi-integrations-history
cardoso Jul 21, 2025
a79e83b
Merge branch 'develop' into feat/openapi-integrations-history
ahmed-n-abdeltwab Sep 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changeset/red-squids-develop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
"@rocket.chat/meteor": patch
"@rocket.chat/rest-typings": patch
---

Add OpenAPI support for the Rocket.Chat integrations.history API endpoints by migrating to a modern chained route definition syntax and utilizing shared AJV schemas for validation to enhance API documentation and ensure type safety through response validation.
148 changes: 116 additions & 32 deletions apps/meteor/app/api/server/v1/integrations.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
import type { IIntegration, INewIncomingIntegration, INewOutgoingIntegration } from '@rocket.chat/core-typings';
import type { IIntegration, INewIncomingIntegration, INewOutgoingIntegration, IIntegrationHistory } from '@rocket.chat/core-typings';
import { Integrations, IntegrationHistory } from '@rocket.chat/models';
import type { PaginatedRequest, PaginatedResult } from '@rocket.chat/rest-typings';
import {
ajv,
isIntegrationsCreateProps,
isIntegrationsHistoryProps,
isIntegrationsRemoveProps,
isIntegrationsGetProps,
isIntegrationsUpdateProps,
Expand All @@ -22,6 +23,7 @@ import { updateIncomingIntegration } from '../../../integrations/server/methods/
import { addOutgoingIntegration } from '../../../integrations/server/methods/outgoing/addOutgoingIntegration';
import { deleteOutgoingIntegration } from '../../../integrations/server/methods/outgoing/deleteOutgoingIntegration';
import { updateOutgoingIntegration } from '../../../integrations/server/methods/outgoing/updateOutgoingIntegration';
import type { ExtractRoutesFromAPI } from '../ApiClass';
import { API } from '../api';
import { getPaginationItems } from '../helpers/getPaginationItems';
import { findOneIntegration } from '../lib/integrations';
Expand All @@ -43,45 +45,118 @@ API.v1.addRoute(
},
);

API.v1.addRoute(
type IntegrationsHistoryProps = PaginatedRequest<{ id: string }>;

const integrationsHistorySchema = {
type: 'object',
properties: {
id: { type: 'string', nullable: false, minLength: 1 },
offset: { type: 'number', nullable: true },
count: { type: 'number', nullable: true },
sort: { type: 'string', nullable: true },
query: { type: 'string', nullable: true },
},
required: ['id'],
additionalProperties: false,
};

const isIntegrationsHistoryProps = ajv.compile<IntegrationsHistoryProps>(integrationsHistorySchema);

const integrationsHistoryEndpoints = API.v1.get(
'integrations.history',
{
authRequired: true,
validateParams: isIntegrationsHistoryProps,
query: isIntegrationsHistoryProps,
permissionsRequired: {
GET: { permissions: ['manage-outgoing-integrations', 'manage-own-outgoing-integrations'], operation: 'hasAny' },
},
response: {
400: ajv.compile<{
error?: string;
errorType?: string;
stack?: string;
details?: string;
}>({
type: 'object',
properties: {
success: { type: 'boolean', enum: [false] },
stack: { type: 'string' },
error: { type: 'string' },
errorType: { type: 'string' },
details: { type: 'string' },
},
required: ['success'],
additionalProperties: false,
}),
401: ajv.compile({
type: 'object',
properties: {
success: { type: 'boolean', enum: [false] },
status: { type: 'string' },
message: { type: 'string' },
error: { type: 'string' },
errorType: { type: 'string' },
},
required: ['success'],
additionalProperties: false,
}),
403: ajv.compile({
type: 'object',
properties: {
success: { type: 'boolean', enum: [false] },
status: { type: 'string' },
message: { type: 'string' },
error: { type: 'string' },
errorType: { type: 'string' },
},
required: ['success'],
additionalProperties: false,
}),
200: ajv.compile<PaginatedResult<{ history: IIntegrationHistory[]; items: number }>>({
type: 'object',
properties: {
history: { type: 'array' },
offset: { type: 'string' },
items: { type: 'integer' },
count: { type: 'integer' },
total: { type: 'integer' },
success: { type: 'boolean', enum: [true] },
},
required: ['success'],
additionalProperties: false,
}),
},
},
{
async get() {
const { userId, queryParams } = this;

if (!queryParams.id || queryParams.id.trim() === '') {
return API.v1.failure('Invalid integration id.');
}

const { id } = queryParams;
const { offset, count } = await getPaginationItems(this.queryParams);
const { sort, fields: projection, query } = await this.parseJsonQuery();
const ourQuery = Object.assign(await mountIntegrationHistoryQueryBasedOnPermissions(userId, id), query);

const { cursor, totalCount } = IntegrationHistory.findPaginated(ourQuery, {
sort: sort || { _updatedAt: -1 },
skip: offset,
limit: count,
projection,
});

const [history, total] = await Promise.all([cursor.toArray(), totalCount]);

return API.v1.success({
history,
offset,
items: history.length,
count: history.length,
total,
});
},
async function action() {
const { userId, queryParams } = this;

if (!queryParams.id || queryParams.id.trim() === '') {
return API.v1.failure('Invalid integration id.');
}

const { id } = queryParams;
const { offset, count } = await getPaginationItems(this.queryParams);
const { sort, fields: projection, query } = await this.parseJsonQuery();
const ourQuery = Object.assign(await mountIntegrationHistoryQueryBasedOnPermissions(userId, id), query);

const { cursor, totalCount } = IntegrationHistory.findPaginated(ourQuery, {
sort: sort || { _updatedAt: -1 },
skip: offset,
limit: count,
projection,
});

const [history, total] = await Promise.all([cursor.toArray(), totalCount]);

return API.v1.success({
history,
offset,
items: history.length,
count: history.length,
total,
});
},
);

Expand Down Expand Up @@ -272,3 +347,12 @@ API.v1.addRoute(
},
},
);

type IntegrationsHistoryEndpoints = ExtractRoutesFromAPI<typeof integrationsHistoryEndpoints>;

export type IntegrationsEndpoints = IntegrationsHistoryEndpoints;

declare module '@rocket.chat/rest-typings' {
// eslint-disable-next-line @typescript-eslint/naming-convention, @typescript-eslint/no-empty-interface
interface Endpoints extends IntegrationsHistoryEndpoints {}
}
22 changes: 0 additions & 22 deletions packages/rest-typings/src/v1/integrations/IntegrationsHistoryProps.ts
View file
Open in desktop

This file was deleted.

1 change: 0 additions & 1 deletion packages/rest-typings/src/v1/integrations/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
export * from './integrations';

export * from './IntegrationsCreateProps';
export * from './IntegrationsHistoryProps';
export * from './IntegrationsRemoveProps';
export * from './IntegrationsGetProps';
export * from './IntegrationsUpdateProps';
Expand Down
10 changes: 1 addition & 9 deletions packages/rest-typings/src/v1/integrations/integrations.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
import type { IIntegration, IIntegrationHistory } from '@rocket.chat/core-typings';
import type { IIntegration } from '@rocket.chat/core-typings';

import type { IntegrationsCreateProps } from './IntegrationsCreateProps';
import type { IntegrationsGetProps } from './IntegrationsGetProps';
import type { IntegrationsHistoryProps } from './IntegrationsHistoryProps';
import type { IntegrationsListProps } from './IntegrationsListProps';
import type { IntegrationsRemoveProps } from './IntegrationsRemoveProps';
import type { IntegrationsUpdateProps } from './IntegrationsUpdateProps';
Expand All @@ -13,13 +12,6 @@ export type IntegrationsEndpoints = {
POST: (params: IntegrationsCreateProps) => { integration: IIntegration };
};

'/v1/integrations.history': {
GET: (params: IntegrationsHistoryProps) => PaginatedResult<{
history: IIntegrationHistory[];
items: number;
}>;
};

'/v1/integrations.list': {
GET: (params: IntegrationsListProps) => PaginatedResult<{
integrations: IIntegration[];
Expand Down
Loading