snapshot of https://github.com/RocketChat/Rocket.Chat.git (develop, 2026-09-16; blobs > 131072B omitted)

apps/meteor/server/api/README.md

@@ -0,0 +1,139 @@
+# API Development Guidelines
+
+## Creating Automatic OpenAPI Specifications
+
+When developing new endpoints or modifying existing ones, follow these guidelines to ensure automatic OpenAPI specification generation and request/response validation.
+
+### Using Status Codes and AJV Schema
+
+1. **Status Codes**: Ensure that each response from your endpoint includes the appropriate HTTP status code.
+2. **AJV Schema Validation**: Use the AJV schema to validate the response structure. This ensures that the response adheres to the defined schema.
+3. **Query and Body Parameters**: Use the new `query` and `body` parameters to validate the inputs to your endpoints. This ensures that the incoming request data adheres to the defined schema.
+
+### Steps to Follow
+
+1. **Define the Schema**: Create a schema for your endpoint response using AJV. This schema will be used to validate the response structure.
+2. **Optional Input Validation**: Optionally, you can validate your input parameters (query and body) using AJV schemas. This helps ensure that the incoming request data adheres to the defined schema.
+3. **Validation in Test Environments**: When an endpoint is created or changed, the response will be validated in TEST environments. If the response does not match the schema, an error will be thrown.
+
+### Deprecation Notice
+
+The `addRoute` method is now deprecated. Instead, use the following methods available inside the API instance:
+
+- `.get`
+- `.post`
+- `.put`
+- `.delete`
+
+These methods provide a more structured and clear approach to defining your API endpoints.
+
+The `validateParams` property is now deprecated. Instead, use the `query` and `body` properties to validate the inputs to your endpoints. This change provides a more structured and clear approach to input validation.
+
+### Example
+
+Here is an example of how to define an endpoint using the new methods and schema validation:
+
+```typescript
+import { API } from 'path/to/api';
+import Ajv from 'ajv';
+
+const ajv = new Ajv();
+
+API.v1
+	.get(
+		'endpoint-name',
+		{
+			authRequired: true,
+			query: ajv.compile({
+					type: 'object',
+					properties: {
+						param1: { type: 'string' },
+						param2: { type: 'number' },
+					},
+					required: ['param1'],
+			}),
+			body: ajv.compile({
+					type: 'object',
+					properties: {
+						field1: { type: 'string' },
+						field2: { type: 'boolean' },
+					},
+					required: ['field1'],
+			}),
+			response: {
+				200: ajv.compile({
+					additionalProperties: false,
+				    type: 'object',
+                    properties: {
+						count: {
+							type: 'number',
+							description: 'The number of sounds returned in this response.',
+						},
+						offset: {
+							type: 'number',
+							description: 'The number of sounds that were skipped in this response.',
+						},
+						total: {
+							type: 'number',
+							description: 'The total number of sounds that match the query.',
+						},
+						success: {
+							type: 'boolean',
+							description: 'Indicates if the request was successful.',
+						},
+						items: {
+							type: 'array',
+							items: {
+								type: 'object',
+								properties: {
+								_id: {
+									type: 'string',
+								},
+								prop1: {
+									type: 'number',
+								},
+								prop2: {
+									type: 'string',
+								},
+								prop3: {
+									type: 'string',
+								},
+							},
+							required: ['_id', 'prop1', 'prop2', 'prop3'],
+							},
+						},
+					},
+				}),
+				401: ajv.compile({
+					additionalProperties: false,
+					type: 'object',
+					properties: {
+						error: {
+							type: 'string',
+						},
+						status: {
+							type: 'string',
+							nullable: true,
+						},
+						message: {
+							type: 'string',
+							nullable: true,
+						},
+						success: {
+							type: 'boolean',
+							description: 'Indicates if the request was successful.',
+						},
+					},
+					required: ['success', 'error'],
+				}),
+			},
+		},
+
+		async function action() {
+			const result = await anyLogic();
+			return API.v1.success(result);
+		},
+	)
+```
+
+By following these guidelines, you ensure that your API endpoints are well-documented, validated, and maintainable.