Registering API endpoints

Introduction
An API endpoint is a location from which APIs can access the resources they need to carry out their function or can post data to it.
In this recipe, we will register a public API endpoint that receives data from external HTTP requests. We will try to forward the data received from the endpoint to the #general channel.
Register an API endpoint
First of all, let's create a new Rocket.Chat app from scratch using rc-apps create. (If rc-apps is an unrecognized command, please check out the Getting Started section to make initial preparations first).
In the main App class, we need to implement the extendConfiguration method, within which we use configuration.api.provideApi to register a new API endpoint new Endpoint(this).
1
// Main App Class
2
import { IAppAccessors, IConfigurationExtend, ILogger } from '@rocket.chat/apps-engine/definition/accessors';
3
import { ApiSecurity, ApiVisibility } from '@rocket.chat/apps-engine/definition/api';
4
import { App } from '@rocket.chat/apps-engine/definition/App';
5
import { IAppInfo } from '@rocket.chat/apps-engine/definition/metadata';
6
​
7
import { Endpoint } from './endpoint';
8
​
9
export class RocketChatTester extends App {
10
    constructor(info: IAppInfo, logger: ILogger, accessors: IAppAccessors) {
11
        super(info, logger, accessors);
12
    }
13
​
14
    public async extendConfiguration(configuration: IConfigurationExtend) {
15
        // Register API endpoints
16
        configuration.api.provideApi({
17
            visibility: ApiVisibility.PUBLIC,
18
            security: ApiSecurity.UNSECURE,
19
            endpoints: [new Endpoint(this)],
20
        });
21
    }
22
}
Copied!
Notice that we imported an Endpoint class from another file. Now let's create a new file named endpoint.ts and implement the class Endpoint we used above.
1
// endpoint.ts
2
import { HttpStatusCode, IHttp, IModify, IPersistence, IRead } from '@rocket.chat/apps-engine/definition/accessors';
3
import { ApiEndpoint, IApiEndpointInfo, IApiRequest, IApiResponse } from '@rocket.chat/apps-engine/definition/api';
4
​
5
export class Endpoint extends ApiEndpoint {
6
    public path = 'api';
7
​
8
    public async post(
9
        request: IApiRequest, endpoint: IApiEndpointInfo, read: IRead, modify: IModify, http: IHttp, persis: IPersistence,
10
    ): Promise<IApiResponse> {
11
        const body = Object.entries(request.content)
12
            .map(([key, value]) => `${key}: ${value}`)
13
            .join('\n');
14
        const room = await read.getRoomReader().getByName('general');
15
​
16
        if (!room) {
17
            return {
18
                status: HttpStatusCode.NOT_FOUND,
19
                content: `Room "#general" could not be found`,
20
            };
21
        }
22
​
23
        const messageBuilder = modify.getCreator().startMessage()
24
            .setText(body)
25
            .setRoom(room);
26
        const messageId = await modify.getCreator().finish(messageBuilder);
27
​
28
        return this.success(JSON.stringify({ messageId }));
29
    }
30
}
Copied!
In the file endpoint.ts, we created a class that extends the base class ApiEndpoint. We defined the path of the API endpoint by assigning the value 'api' to the public property path.
Then, let's implement the method post, which will be executed every time once the API endpoint receives an HTTP POST request from an external service. Following our original idea - forwarding any data received to the #general channel, we obtain the request content by request.content and create a message containing the request content, then send it to the channel #general.
Test the result
Using the CLI command rc-apps deploy to deploy the app to your Rocket.Chat server first. Navigate to Rocket.Chat Admin -> Apps -> Apps Detailed Page to check the full endpoint URL you registered for the App.
Open the terminal and use curl post some data to the endpoint. The result should be like below:
1
> curl --data 'Jack=Hello :)&Lucy=Hi!' -X POST http://localhost:3000/api/apps/public/bc4dd4a1-bf9b-408e-83a4-aba7eba0bf02/api
2
{"messageId":"dREmKaR7qHyN98rtZ"}
Copied!

Storing User Input

Managing Internal State

Last modified 9mo ago

Export as PDF

Copy link

Edit on GitHub

Contents

Introduction

Test the result