Travis CI API 文档

错误处理

注意，在这些示例中，我们省略了身份验证。 一些 JSON 响应也被省略了。

客户端可以读取主页文档以获取可能错误的列表，包括它们的 HTTP 状态代码和可能的附加属性。

curl -H "Travis-API-Version: 3" https://api.travis-ci.com/

{
  "@type":  "home",
  "@href":  "/",
  "errors": {
    "login_required":     {
      "status":                403,
      "default_message":       "login required",
      "additional_attributes": [ ]
    },
    "method_not_allowed": {
      "status":                405,
      "default_message":       "method not allowed",
      "additional_attributes": [ ]
    },
    "not_found":          {
      "status":                404,
      "default_message":       "resource not found (or insufficient access)",
      "additional_attributes": [
        "resource_type"
      ]
    }
  }
}

标识符（例如 not_found）代表错误响应主体中 error_type 字段的潜在值。 请参见以下示例。

curl -H "Travis-API-Version: 3" https://api.travis-ci.com/repo/1000000000

{
  "@type":         "error",
  "error_type":    "not_found",
  "error_message": "repository not found (or insufficient access)",
  "resource_type": "repository"
}

理解错误

错误响应尽可能具有描述性，有时包含额外的字段来帮助客户端理解错误发生的原因。

假设我们被允许读取仓库的用户设置，但不允许更改它。 我们可以通过检查资源的 @permissions 元数据来确认这一点。

curl -H "Travis-API-Version: 3" \
  https://api.travis-ci.com/repo/999/setting/build_pushes

{
  "@type":           "setting",
  "@href":           "/repo/999/setting/build_pushes",
  "@representation": "standard",
  "@permissions":    {
    "read":          true,
    "write":         false
  },
  "name":            "build_pushes",
  "value":           true
}

我们可以看到 write 权限为 false。 然后，更新设置的 PATCH 请求将导致以下错误。

curl -X PATCH \
   -H "Travis-API-Version: 3" \
   -d '{"setting.value":false}' \
   https://api.travis-ci.com/repo/999/setting/build_pushes

{
  "@type":         "error",
  "error_type":    "insufficient_access",
  "error_message": "operation requires write access to user_setting",
  "permission":    "write",
  "resource_type": "user_setting",
  "user_setting":  {
    "@type":           "user_setting",
    "@href":           "/repo/999/setting/build_pushes",
    "@representation": "minimal",
    "name":            "build_pushes",
    "value":           true
  }
}

permission 字段包含在响应中，以及相关资源的 minimal 表示。