[proposal] 材质上传 API

[yushijinhun]

本提案的主要内容：

• 将 Mojang 的材质上传 API 纳入规范。
• 规定了一个角色属性 uploadableTextures，用于表示特定角色可以上传的材质类型。

判断能够上传的材质类型

并非所有验证服务器都允许上传材质，因此本提案新增了一个角色属性 uploadableTextures，用于表示通过 API 能够为角色上传哪些类型的材质。

该属性的值是一个逗号分隔的列表，包含了可以上传的材质类型。材质类型目前有 skin 和 cape 两种。

例如，uploadableTextures 属性的值若为 skin，则表示可以为该角色上传皮肤，但不能上传披风；值若为 skin,cape，则既可以上传皮肤，又可以上传披风。

如果不存在 uploadableTextures 属性，则不能为该角色上传任何类型的材质。

材质上传 API

PUT /api/user/profile/{uuid}/{textureType}
DELETE /api/user/profile/{uuid}/{textureType}

设置或清除指定角色的材质。

URL 参数：

参数	值
uuid	角色的 UUID（无符号）
textureType	材质类型，可以为 skin（皮肤）或 cape（披风）

请求需要带上 HTTP 头部 Authorization: Bearer {accessToken} 进行认证。若未包含 Authorization 头或 accessToken 无效，则返回 401 Unauthorized。

如果操作成功，则返回 204 No Content。

下面分别介绍 PUT 和 DELETE 请求方法的用法：

PUT 上传材质

请求载荷的类型为 multipart/form-data，载荷由以下部分组成：	名称（name）	内容
model	（仅用于皮肤） 皮肤的材质模型，可以为 slim（细胳膊皮肤）或空字符串（普通皮肤）。
file	材质图像，Content-Type 须为 image/png。 建议客户端设置 Content-Disposition 中的 filename 参数为材质图像的文件名，这可以被服务器用作材质的备注。

如果操作成功，则返回 204 No Content。

DELETE 清除材质

清除材质后，该类型的材质将恢复为默认。

注意事项

Mojang 支持 POST https://api.mojang.com/user/profile/{uuid}/{textureType} 这一 API。使用此 API 需要在请求中指定材质 URL，服务器收到请求后，会从指定的 URL 获取材质图像。但考虑到以下安全问题，本提案并未将其纳入：

• 可能导致后端服务器 IP 泄露。
• 可能导致内网渗透。

---

欢迎诸位就本提案提出意见。

[yushijinhun]

更新： 在 「PUT 上传材质」 章节中添加了可选的 filename 参数。

[yushijinhun]

wiki 已更新：1eea92b9d9aa3b99693727f4e2f5fca4e46ecc65