API
前言
这里提供的是 Zammad API v1 说明.
关于 API
这是一个 REST/JSON API. 通过 http 方法请求资源.
资源示例:
GET /api/v1/users
完整的 URL:
https://your_zammad/api/v1/users
实际应用时请把 URL 大刮号{}里的变量替换为实际的数值.
示例:
GET /api/v1/users/{id}
认证
Zammad API 支持三种不同的认证方法.
基于用户密码方式的 HTTP 认证
HTTP 认证需要将用户名和密码放到 http 头部. Zammad 系统管理员可以在系统管理里打开或关闭该种认证方式. 这里有更多关于 HTTP 认证的信息.
示例:
curl -u {用户名}:{密码} https://your_zammad/api/v1/users
基于 HTTP 令牌的认证方式 (访问令牌)
基于 HTTP 令牌的认证方式需要将访问令牌放到 http 头部, 每一位用户都可以在个人偏好设置里设置属于自己的令牌, 而不需要将登录系统的用户名和密码提供出去, 这是安全的方式. Zammad 系统管理员可以在系统管理里打开或关闭该种认证方式.
示例:
curl -H "Authorization: Token token={访问令牌}" https://your_zammad/api/v1/users
OAuth2 (OAuth2 访问令牌)
Zammad API 支持完整的 OAuth2 认证, 这种方式需要由系统管理员创建访问令牌给第三方应用例用. 示例如下:
示例:
curl -H "Authorization: Bearer {访问令牌}" https://your_zammad/api/v1/users
响应格式
由于 Zammad 的 API 接受的数据为 JSON 格式, 所以需要在每次的 HTTP 请求的内容提定如: “Content-Type: application/json”. 否则将得到文本的响应.
示例:
POST /api/v1/users/{id} HTTP/1.1
Content-Type: application/json
{
"name":"some name",
"organization_id": 123,
"note":"some note"
}
使用 cURL 请求的示例
发出请求:
curl -u test@zammad.com:test123 https://xxx.zammad.com/api/v1/users/3
传入数据:
curl -u test@zammad.com:test123 -H "Content-Type: application/json" -X PUT -d '{ json: 'data' }' https://xxx.zammad.com/api/v1/tickets/3
提交数据:
curl -u test@zammad.com:test123 -H "Content-Type: application/json" -X POST -d '{ json: 'data' }' https://xxx.zammad.com/api/v1/users/3
提交数据或文件:
curl -u test@zammad.com:test123 -X POST --form form_id=740354910 --form File=@/workspace/test.jpg https://xxx.zammad.com/api/v1/ticket_attachment_upload
响应格式
如果 Zammad 正确响应的话将会返回 HTTP 2xx-3xx 之间的状态码, 并返回正确的信息, 需要留意的是 updated_at 和 created_at 将会被更新.
示例:
Status: 201 Created
Content-Type:application/json; charset=utf-8
{
"id": 123,
"name":"some name",
"organization_id": 123,
"note":"some note",
"updated_at": "2016-08-16T07:55:42.119Z",
"created_at": "2016-08-16T07:55:42.119Z"
}
响应格式 (扩展)
如果想得到资源的附加信息, 只需要在 URL 里加入参数 expand=true 即可, 例如在这里 organization 是扩展的信息.
示例:
GET /api/v1/users/{id}?expand=true HTTP/1.1
返回的结果像这样:
Status: 200 Ok
Content-Type:application/json; charset=utf-8
{
"id": 123,
"name":"some name",
"organization_id": 123,
"organization": "Some Organization Name",
"note":"some note",
"updated_at": "2016-08-16T07:55:42.119Z",
"created_at": "2016-08-16T07:55:42.119Z"
}
分页
所有的数据均支持分页, 可以在 URL 加入这样参数:
GET /api/v1/users?expand=true&page=1,per_page=5 HTTP/1.1
这样将会得到一页有 5 条数据返回结果:
Status: 200 Ok
Content-Type:application/json; charset=utf-8
[
{
"id": 1,
"name":"some name 1",
"organization_id": 123,
"organization": "Some Organization Name",
"note":"some note",
"updated_at": "2016-08-16T07:55:42.119Z",
"created_at": "2016-08-16T07:55:42.119Z"
},
{
"id": 2,
"name":"some name 2",
"organization_id": 345,
"organization": "Some Other Organization Name",
"note":"some note",
"updated_at": "2016-08-17T07:55:42.221Z",
"created_at": "2016-08-16T09:112:42.221Z"
},
...
]