Travis CI API 文档

Travis CI API 格式

本文档描述了 Travis CI 官方 API 版本 3 遵循的通用格式和原则。

本文档状态

本文档正在大量开发中。规范可能随时更改。

要求

本文档中的关键词“必须”、“禁止”、“必需”、“应”、“不应”、“建议”、“可以”和“可选”的解释方式请参考 RFC 2119。

动机

API 格式应足够直观，熟悉 HTTP 和 JSON 的开发人员应该能够通过检查其有效负载来理解它，前提是他们熟悉 API 公开的业务逻辑。

目标是为 Travis CI 的外部和内部 API 建立一个标准格式。

该格式试图为通用客户端库奠定基础，使其能够快速编写与新 API 端点交互的代码。

JSON 有效负载

API 资源应使用 JSON 作为首选表示形式。资源属性应直接映射到 JSON 键值对。

因此，以下是有效资源

{
  "name": "John Doe",
  "age":  42
}

任何 JSON 有效负载都可能在任何时候包含其他以前未定义的属性。客户端可以选择忽略任何未知属性或公开它们。客户端不应因未知属性而触发错误。

如果表示形式被编码为 JSON，它必须返回一个对象。不允许在顶层返回数组。

元数据

JSON 表示形式可以包含以键值对形式的元数据，其中键以 @ 符号（字节值 64）为前缀。只有本文档中定义的键应该使用。此处定义的元数据键的语义不得更改。

{
  "@type": "user",
  "@href": "/user/John%20Doe",
  "name":  "John Doe",
  "age":   42
}

元数据也可以应用于嵌套对象。

{
  "@type": "user",
  "@href": "/user/John%20Doe",
  "name":  "John Doe",
  "age":   42,
  "home":  {
    "@type":  "address",
    "city":   "Berlin",
    "street": "Rigaer Str. 8"
  }
}

@type

JSON 表示形式应在顶层包含一个 @type 键，并且可以在任何嵌套对象中包含此键。

此键的值标识 JSON 有效负载表示的实体的类型。这允许客户端推断语义、可用操作和包含在同一实体的不同表示形式中的属性。此信息可以从 home 文档（见下文）中得出。

@href

任何在 GET 请求上返回自身 JSON 表示形式的 URI 的实体应在顶层包含 URI 作为 @href 属性。该值可以是相对链接。

在 JSON 有效负载中多次出现的实体可以使用只包含 @href 属性的对象来标识，除了第一次出现之外。

{
  "@type":    "user",
  "@href":    "/user/John%20Doe",
  "name":     "John Doe",
  "age":      42,
  "shipping": {
    "@type":  "address",
    "@href":  "/address/1",
    "city":   "Berlin",
    "street": "Rigaer Str. 8"
  },
  "billing":  {
    "@href":  "/address/1"
  }
}

@pagination

单个响应返回的集合可能代表一个更大集合的子集。要检索更大集合的另一个子集，客户端可以使用 @pagination 字段中公开的元数据。

{
  "@type":       "users",
  "@href":       "/users?limit=1",
  "@pagination": {
    "limit":     1,
    "offset":    0,
    "count":     42,
    "is_first":  true,
    "is_last":   false,
    "next":      {
      "@href":   "/users?limit=1&offset=1",
      "offset":  1,
      "limit":   1
    },
    "prev":      null,
    "first":     {
      "@href":   "/users?limit=1",
      "offset":  0,
      "limit":   1
    },
    "last":      {
      "@href":   "/users?limit=1&offset=41",
      "offset":  41,
      "limit":   1
    }
  },
  "users":       [
    {
      "@type": "user",
      "@href": "/user/John%20Doe",
      "name":  "John Doe",
      "age":   42
    }
  ]
}

@pagination 对象可以包含以下任何字段

字段	描述
limit	当前子集中包含的条目最大数量
offset	位于子集第一个条目之前的条目数量
count	集合中条目的总数
is_first	如果当前子集之前没有条目，则为 true
is_last	如果当前子集之后没有条目，则为 true
next	链接到下一个子集的对象，如果不存在下一个子集，则为 null
prev	链接到上一个子集的对象，如果不存在上一个子集，则为 null
first	链接到第一个子集的对象
last	链接到最后一个子集的对象

next、prev、first 和 last 链接到的集合应该只在它们的 offset 上有所不同，并保持与当前子集相同的 limit。

@permissions

任何包含 @type 字段的对象也可以包含 @permissions 字段。

此字段本身包含一个将键映射到布尔值的对象。这些字段中的每一个代表一个权限，布尔值表示当前客户端是否具有与包含 @permissions 字段的对象相关的权限。

{
  "@type":        "user",
  "@href":        "/user/John%20Doe",
  "name":         "John Doe",
  "age":          42,
  "@permissions": {
    "call_user":     true,
    "share_contact": false
  }
}

要正确使用这些权限，客户端和服务器需要对它们的语义有一个共同的理解。

@representation

任何包含 @type 字段的对象也可以包含 @representation 字段。

对于每个实体，可能存在多个 JSON 表示形式。这些表示形式在包含的字段上有所不同。

如果一个对象支持多个表示形式，它应该包含 @representation 字段。此外，它应该支持 standard 和 minimal 表示形式。

standard 表示形式应用于顶层对象。

minimal 表示形式应该是 standard 表示形式的子集，当实体不是客户端的主要关注点时，它很有用。

包含在多个表示形式中的字段在不同表示形式中不得语义不同。

预定义类型

遵循此格式的 API 可以也应该定义自己的类型来表示其业务对象。但是，为了允许此类 API 的通用使用者推断这些对象以及他们可以在这些对象上执行的操作，需要一些预定义类型。这些类型必须在不同实现之间共享语义。

home

遵循此格式的 API 的主要入口点或主页文档应在顶层返回一个 home 类型的对象。API 的使用者应该使用此对象作为他们将执行的任何其他 API 请求的参考。

home 对象应该包含两个字段：resources 和 errors。

resources 字段包含一个将类型标识符映射到资源描述的对象。这些标识符必须对应于 @type 字段的潜在值。资源描述必须是 resource 类型。

任何对象作为其 @type 字段的值都应该在 resources 字段中有一个条目，或者是一个预定义类型。

errors 字段包含一个将错误标识符映射到错误描述的对象。这描述了 API 返回的特定错误形状。标识符代表 error_type 字段的潜在值。

home 对象也可以包含帮助客户端推断 API 的其他字段。