关键概念

API 结构

Frame.io API 支持一些常见概念，如速率限制、资源集合的分页、版本控制和错误处理。本节将介绍每种概念的具体细节。

组织与风格

API 围绕常见的 REST 原则进行组织。所有请求都应通过 SSL 发起。所有请求和响应体（包括错误消息）均采用 JSON 格式编码。

除非另有说明，API 方法均遵循以下规范：

• 没有值的属性将使用 null，而不是保留为未定义状态 * 属性名称使用“蛇形命名法”（例如：first_name） * 时间戳以 ISO-8601 格式呈现（例如：2016-02-03T16:38:46.985Z）

路径约定

帐户 > 团队 > 项目 > 资产 > 评论

通常，Frame.io API 中的资源路径将遵循上述层级结构模型，深度不超过一个主层级。在直观的情况下，API 支持对逻辑上严格归属某个对象的资源使用独立路径。

例如，Frame.io API 同时支持以下两种路径：

• GET /accounts/:id/teams — 返回帐户下的所有团队。* GET /teams — 返回调用用户的所有团队。* GET /teams/:id — 返回有关特定团队的详细信息。

再举一个例子：评论在其所属资产上下文之外意义不大，因此评论的收集和创建方法都位于资产范围内。但是，如果更新或删除一条评论，资产上下文就不再那么重要，因此会从资源路径中省略：

• GET /assets/:id/comments * POST /assets/:id/comments * PUT /comments/:id * DELETE /comments/:id

权限范围

无论是通过 OAuth2.0，还是直接通过开发者门户获取令牌，所有 API 令牌都必须关联一个明确的“权限范围”列表，这些权限范围是指资源（例如 Asset）和操作（例如 create）的组合，并使用点标记法来表示。例如，具有 asset.create 权限范围的令牌将能够创建新的资产。

如果您使用的是开发者令牌的实施方式，那么权限范围会被设置并分配给访问令牌本身。如果您使用的是 OAuth 应用程序，则会为该应用程序定义权限范围，当用户首次与应用程序交互时，他们会同意授权该应用程序使用所请求的权限范围进行操作。

开发者令牌和应用程序可用的权限范围包括以下内容（请注意，某些权限范围并非对所有人开放，出现问题时会特别说明）。

分页

返回结果集合的 API 方法始终采用分页形式。所有预期返回分页结果的方法都会响应以下查询参数，并返回以下标头属性：

• next — 对应的 URL 是指向下一页的链接。
• prev — 对应的 URL 是指向上一页的链接。
• last — 对应的 URL 是指向最后一页的链接。

**注意：**当 next 和 prev 链接都不存在时，则表示返回的首页就是唯一的一页。