- Print
- DarkLight
- PDF
Register API Endpoints
- Print
- DarkLight
- PDF
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.
![](http://cdn.us.document360.io/27ca1fd4-36d7-4cde-b4eb-97fc1652954c/Images/Documentation/register-api.png?sv=2022-11-02&spr=https&st=2024-09-08T01%3A02%3A22Z&se=2024-09-08T01%3A12%3A22Z&sr=c&sp=r&sig=Cs0YHioRexAvnKJ%2B14AwoSmLip8s1ppLh2bgq6UfoU8%3D)
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
andAPP_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:
![Screenshot 2024-08-14 at 17.54.11.png](http://cdn.us.document360.io/27ca1fd4-36d7-4cde-b4eb-97fc1652954c/Images/Documentation/Screenshot 2024-08-14 at 17.54.11.png?sv=2022-11-02&spr=https&st=2024-09-08T01%3A02%3A22Z&se=2024-09-08T01%3A12%3A22Z&sr=c&sp=r&sig=Cs0YHioRexAvnKJ%2B14AwoSmLip8s1ppLh2bgq6UfoU8%3D)