REST API 概述

前提条件

在开始使用 REST API 之前需要先获取项目 ID 和项目密钥，请进入【配置管理】-【项目信息】页面获取。

REST API 基本约束

• API 被设计为符合 HTTP，REST 规范。例如：查询请求使用 Get 方法，提交请求使用 Post 方法。如果一个请求不是相应的 HTTP 方法，将返回错误。
• 如无特殊说明，调用参数值应转码为：UTF-8，URL 编码。

鉴权方式

极光 REST API 采用 HTTP 基本认证 的验证方式。 基本作法为，HTTP Header（头）里加 Authorization：

          Authorization: Basic ${base64_auth_string}          

        

Header 名称是 "Authorization"，值是 base64 转换过的 "username:password" 对（中间有个冒号）。在运营增长 API 的场景里，username 是 projectId（项目 ID），密码是 projectSecret（项目密钥）。这二者可以在控制台应用设置中查看。 即，上述 base64_auth_string 的生成算法为：base64(projectId:projectSecret)。

鉴权举例

你的 projectId 是 "100102", projectSecret 是 "z7Ls8********WdOvZp"，则调用 Push API v3 时，使用 curl 命令示例如下：

          curl --insecure -X POST -v https://xxx -H "Content-Type: application/json"
-u "100102:z7Ls8********WdOvZp"     

        

HTTP 请求如下：

          > POST /v3/push HTTP/1.1 
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==          

        

返回说明

REST API 描述的所有接口的返回格式均遵循统一的格式标准，标准如下:

• 无论接口调用结果是成功还是失败，返回 http 报文的 content-type 都为 application/json。

• 返回 http 报文 body 的字段规则如下：

  { "code": 0, // 返回code 0表示接口调用成功 非0表示失败，具体不同失败类型的错误码见错误码说明 "msg": "success // 返回提示 如果接口调用失败，会在这个字段提示错误原因 "data": {} // 返回数据，需要返回数据的接口会将数据放在此字段返回 }

            {
    "code": 0, // 返回code 0表示接口调用成功 非0表示失败，具体不同失败类型的错误码见错误码说明     
    "msg": "success // 返回提示 如果接口调用失败，会在这个字段提示错误原因     
    "data": {} // 返回数据，需要返回数据的接口会将数据放在此字段返回 } 
  
          

  此代码块在浮窗中显示

• 返回码说明，返回码包含返回 http 报文中的 http 状态码和上述 body 中的 code。成功的情况下 http 状态码为 200，code 为 0。其它各种异常情况详见各接口的错误码规则。