API

Zammad 的接口文档, 方便与第三方系统对接.

前言

这里提供的是 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_atcreated_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"
  },
  ...
 ]

API 示例

返回目录