API 接口

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

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

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

两种方式可选：

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

• 请求 URL： /api/sessions
• 请求方式： POST
• 消息头：

• Body 信息：

• 返回值：

正常返回一个 Object。

如果出错，返回 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

返回：

{
  "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

GET /api/captchas/1

dev_key默认为永久性 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。

• 示例：

curl -XDELETE -H "X-XTRA-AUTH-ID: cde1f2e1-4930-41c1-a883-0bca35de7ea6" 192.168.1.100:8081/api/sessions

返回：

{
  "code": 200,
  "text": "OK"
}