Register API Endpoints

This document will show how to register a public API endpoint that receives data from external HTTP requests. The data received from the endpoint will then be forwarded to the #general channel.

Register the API endpoint

Create a new Rocket.Chat app from scratch using the command rc-apps create and name it RocketChatTester. If the response indicates that rc-apps is an unrecognized command, refer to the getting started document to use Rocket.Chat Apps-Engine.

Once the app is created, open it in your preferred code editor.

In the main class, RocketChatTesterApp.ts, implement the extendConfiguration method. This method uses configuration.api.provideApi to register a new API endpoint new Endpoint(this). Add the following code to achieve this:

// Main App Class
import { IAppAccessors, IConfigurationExtend, ILogger } from '@rocket.chat/apps-engine/definition/accessors';
import { ApiSecurity, ApiVisibility } from '@rocket.chat/apps-engine/definition/api';
import { App } from '@rocket.chat/apps-engine/definition/App';
import { IAppInfo } from '@rocket.chat/apps-engine/definition/metadata';

import { Endpoint } from './endpoint';

export class RocketChatTester extends App {
    constructor(info: IAppInfo, logger: ILogger, accessors: IAppAccessors) {
        super(info, logger, accessors);
    }

    public async extendConfiguration(configuration: IConfigurationExtend) {
        // Register API endpoints
        await configuration.api.provideApi({
            visibility: ApiVisibility.PUBLIC,
            security: ApiSecurity.UNSECURE,
            endpoints: [new Endpoint(this)],
        });
    }
}

Create the endpoint class

The code above imports an Endpoint class from another file. Now, create this file in the root folder of the app and name it endpoint.ts.

// endpoint.ts
import { HttpStatusCode, IModify, IRead } from '@rocket.chat/apps-engine/definition/accessors';
import { ApiEndpoint, IApiEndpointInfo, IApiRequest, IApiResponse } from '@rocket.chat/apps-engine/definition/api';

export class Endpoint extends ApiEndpoint {
    public path = 'api';

    public async post(
        request: IApiRequest, endpoint: IApiEndpointInfo,
        read: IRead,
        modify: IModify,
    ): Promise<IApiResponse> {
        const body = Object.entries(request.content)
            .map(([key, value]) => `${key}: ${value}`)
            .join('\n');
        const room = await read.getRoomReader().getByName('general');

        if (!room) {
            return {
                status: HttpStatusCode.NOT_FOUND,
                content: `Room "#general" could not be found`,
            };
        }

        const messageBuilder = modify.getCreator().startMessage()
            .setText(body)
            .setRoom(room);
        const messageId = await modify.getCreator().finish(messageBuilder);

        return this.success(JSON.stringify({ messageId }));
    }
}

The code above sets up the Endpoint class in the RocketChatTesterApp folder. In this endpoint.ts file, the Endpoint class is created by extending the base class ApiEndpoint. The API endpoint's path is defined by assigning the value api to the public path property.

Next, the post method is implemented and executed whenever the API endpoint receives an HTTP POST request from an external service. To forward the received data to the #general channel, the “request” content is accessed via request.content. A message containing this content is then created and sent to the #general channel.

Test the result

Start by deploying the app. In the App Info > Details > APIs > POST api section, check the complete endpoint URL you registered for the app.

The POST API will be different depending on your app ID and the endpoint URL on which the app is deployed.

Open the terminal and use curl to post some data to the endpoint. For example, use the following command snippet:

curl -X POST http://ENDPOINT_URL/api/apps/public/APP_ID/api \
-H "Content-Type: application/json" \
-d '{"Jack":"Hello :)", "Lucy":"Hi!"}'

Substitute the ENDPOINT_URL and APP_ID with the appropriate values.

Running the command above will return a response with a messageId. The app bot will also send the “data” attached to HTTP Request as a message to the general channel, as shown below: