Manager API

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>",
    ...
  ],
  "selectedProfile" : "<目前选择的角色的uuid>"
}

新建账号

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

请求格式:

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

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

更新账号信息

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

请求格式:

{
  "banned" : <是否封禁(true/false), 可选>,
  "twitchToken" : "<twitchToken, 空代表未绑定twitch, 可选>"
  "selectedProfile" : "<要选择的角色的uuid, 空代表不选择任何一个角色, 可选>"
}

如果成功更新, 则返回更新后账号的信息, 返回格式同GET /api/accounts/<账号id>. 如果账号不存在, 返回404. 如果要选择的角色不存在, 则返回400, 若要选择的角色并不属于该账号, 返回409.

删除账号

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

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

角色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作为披风的角色, 空串代表没有披风
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, 空串则代表没有披风>",
  "model" : "<角色类型(STEVE/ALEX)>"
}

新建角色

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

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

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

更新角色信息

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

请求格式:

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

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

删除角色

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

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

mc服务端访问控制API

查询规则

// TODO

查询针对某个主机的规则

// TODO

新建规则

// TODO

更新规则

// TODO

删除规则

// TODO

签名密钥管理API

获取密钥

// TODO

上传密钥

// TODO