API鉴权

API使用首部中的Authorization与AuthToken字段进行身份认证与鉴权。

首部鉴权字段

Authorization首部: 用户唯一身份标识，申请API AuthToken响应中的userGuid

AuthToken首部: 用户API认证令牌，申请API AuthToken响应中的authToken

三类鉴权等级

无鉴权: 首部不携带鉴权字段

用户AuthToken鉴权: 首部需携带用户账户申请获得的Authorization与AuthToken

管理员AuthToken鉴权: 首部需携带管理员账户申请获得的Authorization与AuthToken

API文档

API为RESTful风格，响应报文均为JSON格式，Base Url均为api.quetzalsidera.me, 强制使用HTTPS协议

一、申请API AuthToken

鉴权类型: 无鉴权

1.Url

GET /v1/authToken

2.参数

Url参数

参数名	类型	必需	描述
email	string	是	注册使用邮箱
password	string	是	密码

3.响应

根对象

名称	类型	描述
status	num	0: Ok 1001: 邮箱或密码错误
message	string	描述消息
data	object	响应主体

data对象

名称	类型	描述
authToken	string	API认证令牌（首部中的AuthToken）
userGuid	string	用户Guid（首部中的Authorization）
createTimestamp	num	令牌生成时间对应的UTC秒级时间戳（令牌有效期为自此时间起5小时）
isAdmin	bool	是否为管理员

4.请求示例

curl "https://api.quetzalsidera.me/v1/authToken?email=example@example.com&password=123456"

5.响应示例

成功

{
  "status": 0,
  "message": "Ok",
  "data": {
    "authToken": "44cc78fb-c2cc-4a37-bab4-72c4023e3ae0",
    "userGuid": "4254bf69-a6d2-4602-872d-1d1546b25869",
    "createTimestamp": 1760614727,
    "isAdmin": true
  }
}

邮箱或密码错误

{
  "status": 1001,
  "message": "EmailOrPasswordError",
  "data": null
}

备注: 由于本API参数涉及邮箱与注册时密码，请务必在请求时使用HTTPS协议

二、检查认证状态

鉴权类型: 无鉴权

1.Url

GET /v1/authToken/check

2.参数

Url参数

参数名	类型	必需	描述
user_guid	string	是	用户Guid
auth_token	string	是	API认证令牌

3.响应

根对象

名称	类型	描述
status	num	0: Ok 1002: user_guid与auth_token已过期或不存在
message	string	描述消息

4.请求示例

curl "https://api.quetzalsidera.me/v1/authTokenCheck?user_guid=example-guid&auth_token=example-auth-token"

5.响应示例

未过期

{
  "status": 0,
  "message": "Ok",
}

已过期或不存在

{
  "status": 1002,
  "message": "TokenExpired"
}

三、获取管理员列表

鉴权类型: 用户AuthToken鉴权

1.Url

GET /v1/admins

2.参数

无参数

3.响应

根对象

名称	类型	描述
status	num	0: Ok 1003: 权限不足
message	string	描述消息
data	array	管理员邮箱列表

4.请求示例

curl  "https://api.quetzalsidera.me/v1/admins" \
          -H "Authorization: 4254bf69-a6d2-4602-872d-1d1546b25869" \
          -H "AuthToken: 44cc78fb-c2cc-4a37-bab4-72c4023e3ae0"

5.响应示例

成功

{
  "status": 0,
  "message": "Ok",
  "data": [
          "example1@example1.com",
          "example2@example2.com"
  ]
}

权限不足

{
  "status": 1003,
  "message": "Forbidden",
  "data": null
}

四、添加管理员

鉴权类型: 管理员AuthToken鉴权

1.Url

POST /v1/admins

2.参数

表单参数

参数名	类型	必需	描述
mailBox	string	是	要添加的管理员邮箱地址

3.响应

根对象

名称	类型	描述
status	num	0: Ok 1003: 权限不足
message	string	描述消息

4.请求示例

curl -X POST "https://api.quetzalsidera.me/v1/admins" \
          --data-urlencode 'mailBox=example@example.com' \
          -H "Authorization: 4254bf69-a6d2-4602-872d-1d1546b25869" \
          -H "AuthToken: 44cc78fb-c2cc-4a37-bab4-72c4023e3ae0"

5.响应示例

成功

{
  "status": 0,
  "message": "Ok",
}

权限不足

{
  "status": 1003,
  "message": "Forbidden"
}

五、删除管理员

鉴权类型: 管理员AuthToken鉴权

1.Url

DELETE /v1/admins

2.参数

表单参数

参数名	类型	必需	描述
mailBox	string	是	要删除的管理员邮箱地址

3.响应

根对象

名称	类型	描述
status	num	0: Ok 1003: 权限不足
message	string	描述消息

4.请求示例

curl -X DELETE "https://api.quetzalsidera.me/v1/admins" \
     -H "Authorization: 4254bf69-a6d2-4602-872d-1d1546b25869" \
     -H "AuthToken: 44cc78fb-c2cc-4a37-bab4-72c4023e3ae0" \
     --data-urlencode 'mailBox=example@example.com'

5.响应示例

成功

{
  "status": 0,
  "message": "Ok",
}

权限不足

{
  "status": 1003,
  "message": "Forbidden",
}

六、添加好友卡片

鉴权类型: 用户AuthToken鉴权

1.Url

POST /v1/checkList

2.参数

Json请求体

{
  "link": "https://example.com/friend-profile",  // 目标链接
  "pictureLink": "https://example.com/images/profile-pic.jpg", // 头像Url
  "title": {
    "zhCn": "标题",       //卡片标题 简体中文
    "enUs": "title",     //卡片标题 英文（美国）
    "zhHk": "標題",       //卡片标题 繁体中文（香港）
    "zhTw": "標題",       //卡片标题 繁体中文（台湾）
    "enGb": "title",     //卡片标题 英文（英国）
    "jaJp": "タイトル"    //卡片标题 日语
  },
  "comment": {
    "zhCn": "短评",            //卡片短评 简体中文
    "enUs": "comment",        //卡片短评 英文（美国）
    "zhHk": "短評",            //卡片短评 繁体中文（香港）
    "zhTw": "短評",            //卡片短评 繁体中文（台湾）
    "enGb": "comment",        //卡片短评 英文（英国）
    "jaJp": "短いコメント"      //卡片短评 日语
  },
  "addOn": "额外信息或备注内容"     //描述性备注，非展示信息，仅用于审核
}

备注: 头像Url请使用能够直接以GET方法获取到的图像文件，否则可能出现无法显示的问题

若没有这样的文件，源代码中，文件夹QuetzalSidera.Me/wwwroot/img/choices/中也提供了一系列可以选择的图片。若选择该系列的图片，参数pictureLink请填写为 img/choices/文件名。例如选择 IMG_5050.PNG，参数pictureLink请填写img/choices/IMG_5050.PNG

3.响应

根对象

名称	类型	描述
status	num	0: Ok 1003: 权限不足
message	string	描述消息
data	string	卡片Guid，用于各种卡片操作

4.请求示例(请求体保存为data.json文件)

curl -X POST "https://api.quetzalsidera.me/v1/checkList" \
     -H "Authorization: 4254bf69-a6d2-4602-872d-1d1546b25869" \
     -H "AuthToken: 44cc78fb-c2cc-4a37-bab4-72c4023e3ae0" \
     -H "Content-Type: application/json" \
     -d @data.json

4.响应示例

成功

{
  "status": 0,
  "message": "Ok",
  "data": "9a1a8a8a-c1ca-4257-a4db-152ccda550f9"
}

权限不足

{
  "status": 1003,
  "message": "Forbidden",
  "data": null
}

七、获取卡片列表

鉴权类型: 管理员AuthToken鉴权

1.Url

GET /v1/checkList/all

2.参数

无参数

3.响应

根对象

名称	类型	描述
status	num	0: Ok 1003: 权限不足
message	string	描述消息
data	array	卡片列表

4.请求示例

curl -H "Authorization: 4254bf69-a6d2-4602-872d-1d1546b25869" \
     -H "AuthToken: 44cc78fb-c2cc-4a37-bab4-72c4023e3ae0" \
     "https://api.quetzalsidera.me/v1/checkList/all"

5.响应示例

成功

{
  "status": 0,
  "message": "Ok",
  "data": [
    {
      "link": "https://example.com/friend-profile",
      "pictureLink": "https://example.com/images/profile-pic.jpg",
      "title": {
        "zhCn": "标题1",
        "enUs": "title1",
        "zhHk": "標題1",
        "zhTw": "標題1",
        "enGb": "title1",
        "jaJp": "タイトル1"
      },
      "comment": {
        "zhCn": "短评1",
        "enUs": "comment1",
        "zhHk": "短評1",
        "zhTw": "短評1",
        "enGb": "comment1",
        "jaJp": "短いコメント1"
      },
      "addOn": "额外信息或备注内容1"
    },
    {
      "link": "https://example.com/friend-profile",
      "pictureLink": "https://example.com/images/profile-pic.jpg",
      "title": {
        "zhCn": "标题2",
        "enUs": "title2",
        "zhHk": "標題2",
        "zhTw": "標題2",
        "enGb": "title2",
        "jaJp": "タイトル2"
      },
      "comment": {
        "zhCn": "短评2",
        "enUs": "comment2",
        "zhHk": "短評2",
        "zhTw": "短評2",
        "enGb": "comment2",
        "jaJp": "短いコメント2"
      },
      "addOn": "额外信息或备注内容2"
    }
  ]
}

权限不足

{
  "status": 1003,
  "message": "Forbidden",
  "data": null
}

八、检查卡片状态

鉴权类型: 用户AuthToken鉴权

1.Url

GET /v1/checkList

2.参数

Url参数

参数名	类型	必需	描述
cardGuid	string	是	卡片唯一标识

3.响应

根对象

名称	类型	描述
status	num	0: Ok 1003: 权限不足
message	string	描述消息
data	bool	true: 正在审核, false: 审核已结束

4.请求示例

curl -H "Authorization: 4254bf69-a6d2-4602-872d-1d1546b25869" \
     -H "AuthToken: 44cc78fb-c2cc-4a37-bab4-72c4023e3ae0" \
     "https://api.quetzalsidera.me/v1/checkList?cardGuid=933691ea-fdc0-4ea2-b2bc-9621e8b45fd8"

5.响应示例

正在审核

{
  "status": 0,
  "message": "Checking",
  "data": false
}

审核已结束

{
  "status": 0,
  "message": "Finished",
  "data": true
}

权限不足

{
  "status": 1003,
  "message": "Forbidden",
  "data": false
}

九、拒绝卡片审核

鉴权类型: 管理员AuthToken鉴权

1.Url

DELETE /v1/checkList

2.参数

Url参数

参数名	类型	必需	描述
cardGuid	string	是	卡片唯一标识

3.响应

根对象

名称	类型	描述
status	num	0: Ok 1003: 权限不足
message	string	描述消息

4.请求示例

curl -X DELETE \
     -H "Authorization: 4254bf69-a6d2-4602-872d-1d1546b25869" \
     -H "AuthToken: 44cc78fb-c2cc-4a37-bab4-72c4023e3ae0" \
     "https://api.quetzalsidera.me/v1/checkList?cardGuid=933691ea-fdc0-4ea2-b2bc-9621e8b45fd8"

5.响应示例

成功

{
  "status": 0,
  "message": "Ok",
}

权限不足

{
  "status": 1003,
  "message": "Forbidden",
}

十、通过卡片审核

鉴权类型: 管理员AuthToken鉴权

1.Url

POST /v1/checkList

2.参数

Url参数

参数名	类型	必需	描述
cardGuid	string	是	卡片唯一标识

3.响应

根对象

名称	类型	描述
status	num	0: Ok 4001: 卡片Guid不存在 1003: 权限不足
message	string	描述消息

4.请求示例

curl -X POST \
     -H "Authorization: 4254bf69-a6d2-4602-872d-1d1546b25869" \
     -H "AuthToken: 44cc78fb-c2cc-4a37-bab4-72c4023e3ae0" \
     "https://api.quetzalsidera.me/v1/checkList?cardGuid=fa0b5e0c-3a42-4759-a408-c56e8860446a"

5.响应示例

成功

{
  "status": 0,
  "message": "Ok",
}

卡片Guid不存在

{
  "status": 4001,
  "message": "BadRequest"
}

权限不足

{
  "status": 1003,
  "message": "Forbidden"
}

十一、获取位置信息

鉴权类型: 管理员AuthToken鉴权

1.Url

GET /v1/myLocation

2.参数

无参数

3.响应

根对象

名称	类型	描述
status	num	0: Ok 1003: 权限不足
message	string	描述消息
data	string	地点

4.请求示例

curl -H "Authorization: 4254bf69-a6d2-4602-872d-1d1546b25869" \
     -H "AuthToken: 44cc78fb-c2cc-4a37-bab4-72c4023e3ae0" \
     "https://api.quetzalsidera.me/v1/myLocation"

5.响应示例

成功

{
  "status": 0,
  "message": "Ok",
  "data": "深圳"
}

权限不足

{
  "status": 1003,
  "message": "Forbidden",
  "data": null
}

十二、修改位置信息

鉴权类型: 管理员AuthToken鉴权

1.Url

POST /v1/myLocation

2.参数

表单参数

参数名	类型	必需	描述
location	string	是	新的位置信息

4.请求示例

curl -X POST \
     -H "Authorization: 4254bf69-a6d2-4602-872d-1d1546b25869" \
     -H "AuthToken: 44cc78fb-c2cc-4a37-bab4-72c4023e3ae0" \
     --data-urlencode 'location=北京' \
     "https://api.quetzalsidera.me/v1/myLocation"

5.响应示例

成功

{
  "status": 0,
  "message": "Ok",
}

权限不足

{
  "status": 1003,
  "message": "Forbidden"
}

十三、获取已注册用户数量

鉴权类型: 管理员AuthToken鉴权

1.Url

GET /v1/userNum

2.参数

无参数

3.响应

根对象

名称	类型	描述
status	num	0: Ok 1003: 权限不足
message	string	描述消息
data	num	已注册用户数量

4.请求示例

curl -H "Authorization: 4254bf69-a6d2-4602-872d-1d1546b25869" \
     -H "AuthToken: 44cc78fb-c2cc-4a37-bab4-72c4023e3ae0" \
     "https://api.quetzalsidera.me/v1/userNum"

5.响应示例

成功

{
  "status": 0,
  "message": "Ok",
  "data": 1
}

权限不足

{
  "status": 1003,
  "message": "Forbidden",
  "data": 0
}

API鉴权

API文档

一、申请API AuthToken

鉴权类型: 无鉴权

1.Url

2.参数

Url参数

3.响应

根对象

data对象

4.请求示例

5.响应示例

成功

邮箱或密码错误

二、 检查认证状态

鉴权类型: 无鉴权

1.Url

2.参数

Url参数

3.响应

根对象

4.请求示例

5.响应示例

未过期

已过期或不存在

三、获取管理员列表

鉴权类型: 用户AuthToken鉴权

1.Url

2.参数

无参数

3.响应

根对象

4.请求示例

5.响应示例

成功

权限不足

四、添加管理员

鉴权类型: 管理员AuthToken鉴权

1.Url

2.参数

表单参数

3.响应

根对象

4.请求示例

5.响应示例

成功

权限不足

五、删除管理员

鉴权类型: 管理员AuthToken鉴权

1.Url

2.参数

表单参数

3.响应

根对象

4.请求示例

5.响应示例

成功

权限不足

六、添加好友卡片

鉴权类型: 用户AuthToken鉴权

1.Url

2.参数

Json请求体

3.响应

根对象

4.请求示例(请求体保存为data.json文件)

4.响应示例

成功

权限不足

七、获取卡片列表

鉴权类型: 管理员AuthToken鉴权

1.Url

2.参数

无参数

3.响应

根对象

4.请求示例

5.响应示例

成功

权限不足

二、检查认证状态