Skip to content
This repository has been archived by the owner on Apr 6, 2018. It is now read-only.

Manager API

Jump to bottom
Haowei Wen edited this page Feb 18, 2017 · 12 revisions

yggdrasil-backend提供了一组RESTful API用于管理, 位于/api下. 使用json传输数据, Content-Type为application/json; charset=utf-8. 如果调用成功则返回http状态码200, 失败则返回4xx或5xx, 以及以下格式的错误信息

{
  "errorCode" : <错误码>,
  "error" : "<对错误的描述>",
  "stacktrace" : "<发生该错误时的stacktrace, 只有在开启security.showStacktrace后才会包含>"
}

其中errorCode与http状态码相对应, 如400代表请求格式或参数有误, 403代表拒绝访问, 409代表资源存在冲突, 500代表服务器出现内部错误等等. 例如, 下面是一个Not Found错误的信息:

{
  "errorCode" : 404,
  "error" : "HTTP 404 Not Found"
}

账号API

查询账号

请求方法及路径: GET /api/accounts

返回格式:

[
  "账号id1",
  "账号id2",
  ...
]

可以在URL的Query中指定查询参数, 如果没有指定任何参数, 则认为是查询所有账号.

key 例子
accessToken accessToken=abcdefg查询accessToken为abcdefg的账号, 不能为空串, 例如accessToken=就不合法
clientToken clientToken=1234567查询clientToken为1234567的账号, 不能为空串, 例如clientToken=就不合法
banned banned=true查询被封禁的账号, banned=false查询未被封禁的账户
twitchToken twitchToken=1a2b3c4d查询twitchToken为1a2b3c4d的用户, 空串则代表没有绑定twitch的账户(如twitchToken=)

例如, /api/accounts?banned=false&twitchToken= 就查询了所有没被封禁且没绑定twitch的用户.

查询某个账号的信息

请求方法和路径: GET /api/accounts/<账号id>

如果成功, 则返回账号的完整信息. 如果账号不存在则返回404.

返回格式:

{
  "id" : "<账号id>",
  "banned" : <有没有被封禁(true/false)>,
  "twitchToken" : "<twitchToken, 没有绑定twitch则为空串>",
  "profiles" : [ // 该账户的角色列表
    "<角色1的uuid>",
    "<角色2的uuid>",
    ...
  ]
}

新建账号

请求方法和路径: POST /api/accounts

请求格式:

{
  "id" : "<账号id>",
  "banned" : <有没有被封禁(true/false), 可选, 默认false>,
  "twitchToken" : "<twitchToken, 没有绑定twitch则为空串, 可选, 默认为空>",
  "password": "<明文密码，可选，默认为空>"
}

假如说password为空，则该用户是禁止登录的。这里的password在存储时使用sha512+salt进行散列。

如果创建成功, 则返回新账号的完整信息, 返回格式同GET /api/accounts/<账号id>. 如果账号已存在, 则返回409.

更新账号信息

请求方法和路径: POST /api/accounts/<账号id>

请求格式:

{
  "banned" : <是否封禁(true/false), 可选>,
  "twitchToken" : "<twitchToken, 空代表未绑定twitch, 可选>",
  "password": "<明文密码，可选>"
}

如果成功更新, 则返回更新后账号的信息, 返回格式同GET /api/accounts/<账号id>. 如果账号不存在, 返回404.

删除账号

请求方法和路径: DELETE /api/accounts/<账号id>

如果删除成功则返回204 No Content. 若账号不存在则返回404.

登录账户

请求方法和路径: POST /api/login

请求格式:

{
  "username" : "<账户id>",
  "password": "<明文密码>",
  "ignoreBanned": "<即使被ban也进行登录(true/false), 可选, 默认false>"
}

如果成功登录, 则返回账号的信息, 返回格式同GET /api/accounts/<账号id>. 如果登录失败（用户名或密码错误，账户被ban）, 返回403.

角色API

查询角色

请求方法及路径: GET /api/profiles

返回格式:

[
  "角色uuid1",
  "角色uuid2",
  ...
]

可以在URL的Query中指定查询参数, 如果没有指定任何参数, 则认为是查询所有角色.

key 例子
name name=character_查询昵称是character_的角色, 不能为空串
owner owner=account_查询账号account_所属的角色, 不能为空串
banned banned=true查询被封禁的角色, banned=false查询未被封禁的角色
skin skin=http://example.com/skin_.png查询使用http://example.com/skin_.png作为皮肤的角色, 空串代表没有皮肤
cape cape=http://example.com/cape_.png查询使用http://example.com/cape_.png作为披风的角色, 空串代表没有披风
elytra elytra=http://example.com/elytra_.png查询使用http://example.com/cape_.png作为elytra的角色, 空串代表没有elytra
model model=STEVE查询steve类型的角色, model=ALEX查询alex类型的角色, 注意区分大小写
serverId serverId=12345678abcdefg查询12345678abcdefg这个serverId所属的角色, 因为serverId在mc客户端/服务端双方完成登录验证后就会被清除, 所以具有很强的时效性(几秒到几分钟内失效)

例如, /api/profiles?banned=true&skin=ALEX&skin=&cape= 查询了所有被封禁的, 使用默认皮肤和披风的(或者说没有披风和皮肤的) alex角色.

查询某个角色的信息

请求方法和路径: GET /api/profiles/<角色uuid>

如果成功, 则返回角色的完整信息. 如果角色不存在则返回404.

返回格式:

{
  "uuid" : "<角色uuid>",
  "name" : "<昵称>",
  "owner" : "<所属账号id>",
  "banned" : <是否被封禁(true/false)>,
  "skin" : "<皮肤的URL, 空串则代表没有皮肤>",
  "cape" : "<披风的URL, 空串则代表没有披风>",
  "elytra" : "<elytra的URL, 空串则代表没有elytra>",
  "model" : "<角色类型(STEVE/ALEX)>"
}

新建角色

请求方法和路径: POST /api/profiles

请求格式:

{
  "uuid" : "<角色uuid, 可选, 默认随机生成>",
  "name" : "<昵称>",
  "owner" : "<所属账号id>",
  "banned" : <是否被封禁(true/false), 可选, 默认false>,
  "skin" : "<皮肤的URL, 空串则代表没有皮肤, 可选, 默认为空>",
  "cape" : "<披风的URL, 空串则代表没有披风, 可选, 默认为空>",
  "elytra" : "<elytra的URL, 空串则代表没有elytra, 可选, 默认为空>",
  "model" : "<角色类型(STEVE/ALEX), 可选, 默认为STEVE>"
}

如果创建成功, 则返回新角色的完整信息, 返回格式同GET /api/profiles/<角色uuid>. 如果角色已存在, 或昵称发生冲突, 则返回409. 如果属主账号不存在, 则返回400.

更新角色信息

请求方法和路径: POST /api/profiles/<角色uuid>

请求格式:

{
  "name" : "<新的昵称, 可选>",
  "banned" : <是否封禁(true/false), 可选>,
  "skin" : "<皮肤的URL, 空串则代表没有皮肤, 可选>",
  "cape" : "<披风的URL, 空串则代表没有披风, 可选>",
  "elytra" : "<elytra的URL, 空串则代表没有elytra, 可选>",
  "model" : "<角色类型(STEVE/ALEX), 可选>"
}

如果成功更新, 则返回更新后角色的信息, 返回格式同GET /api/profiles/<角色uuid>. 如果角色不存在, 返回404. 如果新的昵称和其它角色发生冲突, 返回409.

删除角色

请求方法和路径: DELETE /api/profiles/<角色uuid>

如果删除成功则返回204 No Content. 若角色不存在则返回404.

mc服务端访问控制API

本功能用于在玩家加入服务器的验证过程中, 对发送hasJoinedServer的mc服务端进行鉴权, 防止玩家加入未经授权的服务器. 主要根据访问者的ip地址进行访问控制. 对于每个ip都可以指定相应的访问策略, 如允许或阻止, 如果没有与之对应的访问策略, 则使用默认策略.

查询规则

请求方法及路径: GET /api/rules

返回格式:

[
  {
    "host": "<ip地址1>",
    "policy": "<针对该ip的访问策略>"
  },
  {
    "host": "<ip地址2>",
    "policy": "<针对该ip的访问策略(ALLOW/DENY)>"
  },
  ...
]

注意: ip地址为default代表该条规则为默认规则.

可以在URL的Query中指定查询参数, 如果没有指定任何参数, 则认为是查询所有规则.

key 例子
policy policy=ALLOW查询所有允许的规则, policy=DENY查询所有阻止的规则

查询针对某个主机的规则

请求方法及路径: GET /api/rules/<ip地址>

如果成功, 则返回该规则的信息. 如果规则不存在则返回404.

返回格式:

{
  "host" : "<ip地址>",
  "policy" : "<针对该ip的访问策略(ALLOW/DENY)>"
}

新建规则

请求方法及路径: POST /api/rules

请求格式:

{
  "host" : "<ip地址>",
  "policy" : "<针对该ip的访问策略(ALLOW/DENY)>"
}

如果创建成功, 则返回该规则的信息, 返回格式同GET /api/rules/<ip地址>. 如果规则已存在, 则返回409.

更新规则

请求方法及路径: POST /api/rules/<ip地址>

请求格式:

{
  "policy" : "<针对该ip的访问策略(ALLOW/DENY)>"
}

如果更新成功, 则返回该规则的信息, 返回格式同GET /api/rules/<ip地址>. 如果规则不存在, 则返回404.

删除规则

请求方法及路径: DELETE /api/rules/<ip地址>

如果删除成功则返回204 No Content. 若规则不存在则返回404.

签名密钥管理API

该API提供了对数字签名私钥的管理. 数字签名使用RSA密钥.

获取密钥

请求方法及路径: GET /api/privatekey.der

返回一个未加密的DER格式的PKCS8 RSA私钥, Content-Type为application/octet-stream. 如果没有密钥(即没有开启签名功能), 则返回一个零长度的流.

注意: 如果security.allowDownloadPrivateKey为false, 则请求会被拒, 返回403.

上传密钥

请求方法及路径: POST /api/privatekey.der

请求格式: Content-Type为application/octet-stream, 请求体为一个未加密的DER格式的PKCS8 RSA私钥, 如果想要将私钥设置为null(即关闭数字签名功能), 则请求体可以为一个零长度流.

注意: 如果security.allowUploadPrivateKey为false, 则请求会被拒, 返回403.

Clone this wiki locally