How to call RESTful API

This page explains the structure of the channel management RESTful API and how to call it correctly.

Before calling the API, make sure you have the following:

• An Agora app ID
• Customer ID
• Customer key

Following is a sample request URL:

_1

https://api.agora.io/dev/v1/kicking-rule

• https: The communication protocol. Agora uses HTTPS.
• api.agora.io: The domain name of the Agora server.
• dev/v1/kicking-rule: The resource path, including the API version and the resource name.

The above example is for reference only. Refer to the documentation of the API you want to call, select the method (GET, POST, PUT, PATCH, DELETE) in the code source file or debug application, and then configure the actual request URL according to your needs. The request URL is case-sensitive.

A request consists of two parts: The request header and the request body.

The following example shows how to create a privilege banning rule by sending a POST request containing the app ID, channel name, user ID, user IP, ban duration, and the privilege list to the specified API address:

_14

curl --location --request POST 'https://api.agora.io/dev/v1/kicking-rule' \

_14

--header 'Content-Type: application/json' \

_14

--header 'Accept: application/json' \

_14

--header 'Authorization: <http_basic_auth>' \

_14

--data '{

_14

"appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",

_14

"cname": "channel1",

_14

"uid": 589517928,

_14

"ip": "123",

_14

"time": 60,

_14

"privileges": [

_14

"join_channel"

_14

]

_14

}'

The request header contains the following information needed to process the request:

• Accept: Tells the server what types of responses the client can handle, such as application/json.
• Authorization: The Agora RESTful API requires HTTP authentication. Every time you send an HTTP request, fill in the Authorization field in the request header. See RESTful authentication for details.
• Content-Type: Specifies the type of the request body, such as application/json.

The request body contains the information to be sent to the server. For example, to create a new rule to ban user privileges, include the relevant information, such as the app ID, channel name, user ID, user IP, ban duration, and the banned privileges. The request body is case-sensitive.

After you send the request, the Agora server sends a response that includes a response status code and a response body. The channel management RESTful API does not have a response header.

The HTTP response status code can be one of the following:

• 200: The request is successful.
• Other than 200: Refer to Response status codes to troubleshoot the problem.

The response body contains the information returned by the server. For example, the response body of creating a banning rule includes the request status and the rule ID.

The following is a response example for creating a banning rule:

_4

{

_4

"status": "success",

_4

"id": 1953

_4

}

If you encounter a problem, use developer tools to view the request and response, and troubleshoot based on the response status code. If the problem persists, contact technical support.