REST API overview - Jiguang Docs

Server REST API Overview

UMS provides HTTP APIs that comply with REST specifications for developers to remotely call services provided by UMS.

Basic REST API Constraints

APIs are designed to comply with HTTP and REST specifications.
Unless otherwise specified, call parameter values should be encoded as UTF-8 and URL encoded.
API requests have rate limits.

API Resource List

Name	Resource	Description
Normal Message Sending	POST https://api.ums.jiguang.cn/v1/broadcast	Broadcast sending
Normal Message Sending	POST https://api.ums.jiguang.cn/v1/sent	Other sending methods
Template Message Sending	POST https://api.ums.jiguang.cn/v1/template/broadcast	Broadcast sending
Template Message Sending	POST https://api.ums.jiguang.cn/v1/template/sent	Other sending methods
Message Retraction	POST https://api.ums.jiguang.cn/v1/retract/{msgid}	Retract one message
User Management	POST https://api.ums.jiguang.cn/v1/user/opt	Batch add and update user information
User Management	POST https://api.ums.jiguang.cn/v1/user/delete	Batch delete user information
Material Management	POST https://api.ums.jiguang.cn/v1/material	Manage materials, upload or download
Obtain Channel Token	GET https://api.ums.jiguang.cn/v1/token?type={type}	Obtain authentication tokens for each channel

Authentication Method

Jiguang REST APIs use HTTP Basic Authentication.

The basic method is to add Authorization to the HTTP Header:

Authorization: Basic ${base64_auth_string}

The header name is "Authorization", and the value is the Base64-encoded "username:password" pair, with a colon in between. In the UMS API scenario, username is ChannelKey and password is MasterSecret. Both can be viewed in Basic Settings -> Channel Information in the UMS Web console.

The generation algorithm for base64_auth_string is: base64(ChannelKey:MasterSecret).

Note: When calling user management APIs, you can also use a dedicated AccessKey and MasterSecret for authentication.

Authentication Example

If your ChannelKey is "7d431e42dfa6a6d693ac2d04" and MasterSecret is "5e987ac6d2e04d95a9d8f0d1", when sending a template message using curl, write it as follows:

curl --insecure -X POST -v https://api.ums.jiguang.cn/v1/template/sent -H "Content-Type: application/json" -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" -d ' { "template_id":10001, "template_para":{"user":"xxx","url":"xxx"}, "app_para":{ "platform":"ios", "time_to_live":9999, "big_push_duration":10, "apns_production":true }, "aud_xxx": xxx, "option": { "sendno": "test_mail", "expire_time": 1602523317, "owner":"admin", "black_id":1234, "white_id":1234, "priority":2 } }'

          curl --insecure -X POST -v https://api.ums.jiguang.cn/v1/template/sent -H "Content-Type: application/json"
-u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1"
-d '
{
 "template_id":10001,
 "template_para":{"user":"xxx","url":"xxx"},
 "app_para":{ 
 "platform":"ios",
 "time_to_live":9999,
 "big_push_duration":10,
 "apns_production":true
 },
 "aud_xxx": xxx,
 "option": {
 "sendno": "test_mail",
 "expire_time": 1602523317,
 "owner":"admin",
 "black_id":1234,
 "white_id":1234,
 "priority":2
 }
}'

This code block is shown in the floating window

The HTTP request sent is:

> POST https://api.ums.jiguang.cn/v1/template/sent HTTP/1.1 > Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

          > POST https://api.ums.jiguang.cn/v1/template/sent HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

This code block is shown in the floating window

API Rate Control

UMS APIs have rate control for access count. Within a certain time window, the number of API calls allowed is limited.

Rate Definition

The number of API calls per AppKey within one time window.

The following table shows API rates for the VIP version. The free version uses shared channels and has lower rates than VIP:

API Type	Rate	Description
Broadcast message sending	100 messages/day	Normal message and template message sending share the same rate. Exceeding the rate returns error 1015029.
Other message sending methods	600 times/minute	Normal message and template message sending share the same rate. Exceeding the rate returns error 1015030.
User management	600 times/minute	Add, update, and delete APIs share the same rate. Exceeding the rate returns error 1015030.

To upgrade to VIP or increase the VIP rate further, contact sales.

Exceeding the Rate Limit

When a request hits the rate limit, the UMS API returns the corresponding error code. Example:

{ "code": 1015030, "message": "api请求超出频率限制" }

          {
 "code": 1015030, 
 "message": "api请求超出频率限制"
}

This code block is shown in the floating window

Rate Optimization Suggestions

Distribute requests evenly across time windows.
When making many requests based on tags or user IDs, avoid invalid tags and user IDs.
If many requests for tags or user IDs have the same content, multiple recipients can be filled in for each call.