Get Started with Agora RESTful APIs

Agora offers a growing number of RESTful APIs for extending the features of live voice and video applications. This includes Cloud Recording, Real-Time Transcription, and RTMP integrations.

To make using these RESTful APIs from your infrastructure easier, Agora’s developer community has released the open-source project, Agora Middleware Service. This Go-based backend provides a set of RESTful APIs for token generation, cloud recording management, and real-time transcription. It simplifies integrating features that require Agora’s cloud services into your existing real-time voice and video applications.

The project serves two primary purposes:

1. For front-end developers, it provides a ready-to-use backend that handles Agora API interactions, allowing you to focus on building your application’s user interface and features.
2. For backend developers, it offers a quick deployment option to support front-end teams working with Agora SDKs, reducing the time and effort needed to set up a custom backend.

Using this middleware, developers can offload complex and time-consuming server-side builds and focus on delivering great user experiences in their real-time applications.

Key features of the middleware include:

• Token generation for RTC, RTM, and Chat services
• Cloud recording management (start, stop, update layout, etc.)
• Real-time transcription control
• RTMP push and pull services
• Configurable storage options for recordings and transcriptions
• Easy-to-use RESTful API endpoints

Let’s dive into setting up and using this powerful tool!

Prerequisites

Before you begin, make sure you have the following:

1. Go (version 1.16 or later) installed on your system
2. An Agora developer account (if you don’t have one, sign up at https://www.agora.io/)
3. Your Agora App ID and App Certificate
4. Your Agora Customer ID and Customer Secret
5. A cloud storage provider: Amazon S3, Alibaba Cloud, Tencent Cloud, Microsoft Azure, Google Cloud, Huawei Cloud, Baidu IntelligentCloud
6. Basic knowledge of RESTful APIs and JSON

Installation

To get started with the Agora Middleware Service, first clone the repo:

git clone https://github.com/AgoraIO-Community/agora-go-backend-middleware.git

Navigate to the project directory:

cd agora-go-backend-middleware

Install the required dependencies:

go mod download

Configuration

A properly configured environment is crucial for the middleware to function. To set up your environment, first copy the example environment file:

cp .env.example .env

Then, open the .env file in your favorite text editor and fill in the required values:

APP_ID=your_agora_app_id
APP_CERTIFICATE=your_agora_app_certificate
CUSTOMER_ID=your_customer_id
CUSTOMER_SECRET=your_customer_secret
CORS_ALLOW_ORIGIN=*
SERVER_PORT=8080
STORAGE_VENDOR=
STORAGE_REGION=
STORAGE_BUCKET=
STORAGE_BUCKET_ACCESS_KEY=
STORAGE_BUCKET_SECRET_KEY=
# Agora Endpoint Config (default)
AGORA_BASE_URL=https://api.agora.io/
AGORA_CLOUD_RECORDING_URL=v1/apps/{appId}/cloud_recording
AGORA_RTT_URL=v1/projects/{appId}/rtsc/speech-to-text
AGORA_RTMP_URL=v1/projects/{appId}/rtmp-converters
AGORA_CLOUD_PLAYER_URL=v1/projects/{appId}/cloud-player

1. Make sure to replace the placeholder values with your actual Agora credentials and desired configuration options.
2. Fill in the appropriate storage configuration values if you’re using cloud storage for recordings or transcriptions.
3. The default Agora endpoints are provided, you shouldn’t need to edit these values.

Running the Service

Now that you’ve configured the service, it’s time to run it. We have a few options.

Using Go:

go run cmd/main.go

Using Docker and Make:

make build 
make run

If everything is set up correctly, you should see the output in your console indicating that the server is running on http://localhost:8080 (unless you've specified a different port in the .env file).

API Overview

The middleware service exposes endpoints for Token Generation, Agora Cloud Recording, Agora Real-Time Transcription, and Agora’s RTMP (Push & Pull) services. Let’s explore each set of endpoints and how to use them.

Token Generation

The Token Generation API allows you to create access tokens for audio and video streams on Agora’s network. These tokens are essential for authenticating users and maintaining the security of your application.

Endpoint: POST /token/getNew

You can generate tokens for:

• RTC (Real-Time Communication)
• RTM (Real-Time Messaging)
• Chat

Check out examples using cURL commands to generate tokens.

Cloud Recording

The Cloud Recording API provides endpoints for managing cloud recording sessions. This includes starting and stopping recordings, updating layouts, and getting the status of recording resources.

Key endpoints:

• Start Recording: POST /cloud_recording/start
• Stop Recording: POST /cloud_recording/stop
• Get Recording Status: GET /cloud_recording/status
• Update Layout: POST /cloud_recording/update/layout

Check out examples using cURL commands to manage cloud recordings.

Real-Time Transcription

The Real-Time Transcription (RTT) API allows developers to control transcription sessions, enabling speech-to-text conversions and translations in real-time during Agora calls.

Key endpoints:

• Start RTT: POST /rtt/start
• Stop RTT: POST /rtt/stop/:taskId
• Query RTT Status: GET /rtt/status/:taskId

Check out examples using cURL commands to manage real-time transcription sessions.

RTMP Service

The RTMP (Real-Time Messaging Protocol) Service provides APIs for managing RTMP push and pull operations. This allows developers to stream media to 3rd party streaming services that use RTMP and to pull streams into Agora channels from CDN storage or other RTMP-based broadcasts.

RTMP Push (RTMP Converter)

RTMP Push, also known as RTMP converter enables streaming content from an Agora channel to an RTMP destination.

Key endpoints:

• Start Push: POST /rtmp/push/start
• Stop Push: POST /rtmp/push/stop
• Update Push: POST /rtmp/push/update
• List Push: GET /rtmp/push/list

RTMP Pull (Cloud Player)

RTMP Pull, also referred to as Cloud Player, pulls RTMP streams into an Agora channel.

Key endpoints:

• Start Pull: POST /rtmp/pull/start
• Stop Pull: POST /rtmp/pull/stop
• Update Pull: POST /rtmp/pull/update
• List Pull: GET /rtmp/pull/list

Check out examples using cURL commands to manage RTMP converters and cloud players.

Both RTMP Push and Pull services support various configuration options for audio and video, allowing fine-tuned control over the streaming process. Remember to handle the responses appropriately in your application to manage the RTMP sessions effectively.

Testing the APIs

With the service running, it’s time to test it and ensure it’s working correctly. To test the APIs you can use the cURL commands above or with tools like Bruno or Postman. We’ve prepared a comprehensive set of examples for each service.

• Bruno: agora-backend-middleware.bru
• Postman: Agora Backend Middleware.postman_collection

Remember to replace localhost:8080 with the appropriate address if your service is running on a different host or port. Also, make sure to update any placeholder values (like channel names, UIDs, etc.) with real values that match your testing environment.

Best Practices

To make the most of the Agora Middleware Service, consider the following best practices:

1. Security: Always use HTTPS in production environments to encrypt data in transit.
2. Error Handling: Use proper handling of your client applications to manage API responses gracefully.
3. Rate Limiting: Be mindful of Agora’s API rate limits and implement appropriate throttling mechanisms if necessary.
4. Logging: Enable and monitor logs to track usage and troubleshoot issues.
5. Regular Updates: Keep the middleware service updated to benefit from the latest features and security improvements.

Troubleshooting

If you encounter issues while setting up or using the middleware service, try the following:

1. Double-check your .env configuration to ensure all values are correct.
2. Verify that your Agora account is active and your project has the necessary services enabled.
3. Check the console output for any error messages or logs.
4. Ensure your firewall or network settings are not blocking the service.
5. Verify that the required ports are open and accessible.

Support

If you need further assistance or have questions about the Agora Middleware Service, you have several options:

1. Visit the official Agora documentation for detailed information about Agora’s services and additional resources.
2. Open an issue on the GitHub repository if you find a bug or have a feature request.

The Agora team is here to help and support our community succeed in building amazing real-time communication applications.

Happy coding, and we can’t wait to see what you’ll build with Agora!