REST API文档

API 接口

认证

系统使用基于 Session 的认证方式。

通过认证 API 拿到 Token 后,即可携带其访问有权限认证的接口。

如果开启了图形验证码,在最开始调用时,无须图形验证码,当接口获取错误 2 次,则需要先获取验证码,然后根据账号、密码、验证码再次获取 token,当输入错误 5 次后则锁定获取接口,2 小时之内不可获取 Token。

登录

两种方式可选:

  • 1)使用用户名密码获取 token
  • 2)也可以在后台的用户设置页面,申请 dev_key 来代替密码,获取 token。(详见 开发集成指南
  • 3)通过 2)获取到的 dev_key 也可以代替 token 登录调用(慎用)

获取 Token

  • 请求 URL/api/sessions
  • 请求方式POST
  • 消息头
参数必选类型备注
Content-Typestringapplication/jsonapplication/x-www-form-urlencoded
  • Body 信息
参数必选类型备注
loginstring用户名
passwordstring密码
dev_keystring开发密钥,如果loginpassword不存在则为必选
  • 返回值

正常返回一个 Object。

返回字段必选类型备注
codeint结果码
tokenstringToken (即 X-XTRA-AUTH-ID)

如果出错,返回 HTTP 状态码如403等,详见HTTP 状态码参考JSON 返回格式参考

  • 其它说明

首先,用用户名和密码获取一个 Token,参数的提交方式有两种,一种是基于 URL 字符串(www-form-urlencoded),如:

curl -XPOST -d 'login=1007&password=$VeryGoodPassw0rd' 192.168.1.100:8081/api/sessions

或者使用dev_key代替密码

curl -XPOST \
-d 'login=1007&dev_key=1547798578ed48b611-44e0-45ac-9642-92510e357811' \
192.168.1.100:8081/api/sessions

也可以提交一个 JSON 请求,如:

curl -XPOST -d '{"login": "1007", "password": "$VeryGoodPassw0rd"}' \
-H "Content-Type: application/json" \
192.168.1.100:8081/api/sessions

返回:

状态码说明返回值
200成功{"code": 200, "token": "cde1f2e1-4930-41c1-a883-0bca35de7ea6"}
403鉴权失败{code = 403, text = "Wrong username or password"}
{
  "system_roles": {
    "senior_roles_str": "()",
    "roles_str": "()"
  },
  "extn": "1001",
  "code": 200,
  "currentAuthority": "admin",
  "expires": 1652290471,
  "user_id": 3,
  "token": "cde1f2e1-4930-41c1-a883-0bca35de7ea6"
}

后续所有的请求(包括注销)都需要使用该token。如

curl -H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" \
192.168.1.100:8081/api/users

图形验证码

生成验证码

根据用户名查找用户 id,生成对应 id 的验证码图片

GET /api/captchas?login=admin

根据 id 获取图片

GET /api/captchas/1

特别注意dev_key

dev_key默认为永久性 Token,当系统重启后,此值不会失效,因此在开发使用时需特别谨慎,不建议在前端调用。如果采用后端开发,可根据需要建立并使用。

启用图形验证码后获取 token

当用户名、密码错误超过两次后,需要先获取图形验证码,再调用 api/sessions,如下

GET /api/captchas

获取图形验证码 ID

{
	"message": "success",
	"code": 200,
	"data": {
		"captcha_id": 42,
		"pic_path": "/api/captchas/42"
	}
}

GET /api/captchas/42

获取图形验证码图片,比如dOnW

再调用POST api/sessions

BODY 内容

{
    "login":"admin",
    "password":"XSwitch.cn/6753997",
    "captcha_str":"dOnW"
}
curl -XPOST -d '{"login": "1007", "password": "$VeryGoodPassw0rd","captcha_str":"dOnW"}' \
-H "Content-Type: application/json" \
192.168.1.100:8081/api/sessions

注销

  • 请求 URL/api/sessions
  • 请求方式DELETE
  • 消息头: 无
  • Body 信息:无
  • 返回值

正常返回一个 Object。

返回字段必选类型备注
codeint结果码
textstring描述字符串
  • 示例
curl -XDELETE -H "X-XTRA-AUTH-ID: cde1f2e1-4930-41c1-a883-0bca35de7ea6" 192.168.1.100:8081/api/sessions

返回:

状态码说明返回值
200成功{"code":200, "text":"OK"}
404失败{"code": 404, "text": "Session Does Not Exist"}
500失败{"code": 500, "text": "Internal Error"}
{
  "code": 200,
  "text": "OK"
}
综述