API实践

API有可以从web浏览器访问的用户接口。这是查看资源，执行动作，以及查看等价于cURL命令执行的HTTP请求&回应。点击API来获得URL endpoint来访问API。

点击端点链接：

术语

API中一些资源类型命名和当前UI上所用的术语，并不一致。尤其是：

在这文档中，我们使用UI所用的术语进行描述，在不同点也会提供额外的声明。这些混乱将会在未来的/v2版本API清除。

验证

如果Access Control启动的话，API请求必须包含验证信息。验证操作通过带有API keys的HTTP基本验证来完成。API密钥或者属于一个(UI) Environment/ (API) Project，只能访问该Environment；或者属于一个Account，能够访问该账户所有的Environment，也能够创建新的Api密钥。在UI上有单独的JSON Web Token接口。

一个环境的API密钥

环境的API密钥能够在UI中创建，查看[API & Kes[({{site.baseurl}}/configuration/api-keys/)。 密钥所属于一个环境，而且完全有权管理该环境，但无权管理其他环境。Membership roles并不支持密钥。

账户的API密钥

账户的API密钥当前并没有在UI中显示。你可以点击浏览器的API页面来创建一个:

• 点击UI上的Endpoint链接
• 导航到/v1/apikeys
• 点击Create
• 选择你要创建密钥的accountId
• 可选择设置name和description
• 点击Show Request， 然后Send Request
• 保存回应中的publicValue和secretValue

Account密钥能够创建新的Environments，也能够用来通过/v1/projects来访问多个Environments。这些密钥所采用的Membership roles限制该Account哪些Environments以及哪些动作能够使用。

作用域

• 大部分的资源被一个Environment所拥有，并通过/v1/projects/<project_id>/<resources>地址进行访问。
• 因为环境证书只能够存取一个Environment(project)，你可以选择跳过/project/<project_id>部分。
  -例如，如果你在project 1a5使用了一个Environment API密钥，那么/v1/projects/1a5等同于v1，/v1/projects/1a5/hosts等同于/v1/hosts。
• 这篇文档一般只涉及更短的/v1/<type>版本.如果使用了Account密钥，则将适当的environment添加到路径中。

发送请求

这些API一般都是RESTful API，但拥有一些特性使得客户端能够查看任何资源的定义，因而可以编写通用的客户端，而不是每种资源类型编写特定代码的客户端。对那些想费力深入通用API规范细节的人，查看这里

• 每种类型有一个Schema，负责描述：

  • 到达该资源类型的collection的URL
  • 该资源拥有的所有域，连同域的类型，域的基本验证规则，它们是必须还是可选等.
  • 该类型资源能够执行每个动作，以及输入和输出(和schemas一样)
  • 每个域允许的过滤方式
  • collection中哪些HTTP动词方法对其或者其中独立的资源可用

• 因此理论上你能够只需要加载schemas列表就知道API的一切。这就是实际上UI如何工作的，它并没有包含和Rancher特定的代码。获取Schemas的URL，作为一个X-Api-Schemas头部，在每一个HTTP回应被发送。从该URL，你可以通过访问每一个schema的collection链接，来知道哪里显示资源；通过返回资源的其他links来获取其他信息。

• 实际上，你可能只想构建URL字符串。我们强烈建议限制构建的URL字符串只在顶级显示collection(/v1/<type>)或者获取一个特定的资源(/v1/<type>/<id>)时使用。任何更底层的动作都将在将来版本改变。(译者注：这里指用户应尽通过可能返回的HTTP回应信息中提取想要资源的URL，不要根据当前版本资源的URL结构自己构建。)

• 资源间的关系称为links。每个资源都包含一个links表，其中包含link的名字以及获取link信息的URL. 再次强调，你应该通过发送GET请求来获取资源以及使用links表中的URL，而不是自己构建这些字符串。

• 大多数资源都有些动作，用来处理某事或者改变资源的状态. 通过发送POST请求到action表中的URL来执行你想要的动作. 一些动作会需要输入或者会产生输出，请查看每种类型资源或者schemas的独立文档来获取特定信息.

• 编辑资源， 则发送一个带有资源的域数据的PUTHTTP请求到你想要改变的资源的links.self链接.未知域或者不可编辑的域将被忽略.

• 删除资源， 则发送一个DELETEHTTP请求到资源的links.self链接. 注意一些资源必须要在删除之前停止;被删除的资源仍然通过API根据指定资源ID来恢复.

• 创建资源，发送一个POSTHTTP请求schema中的collection URL(也即是/v1/<type>).

过滤

大多数的collections能够在服务端通过HTTP的检查参数按照通用域进行过滤.filter表显示哪些域能够被过滤， 以及哪些值是你的请求过滤的. API UI控制了安装过滤的过程，为你显示正确的请求。”equals”和field=value相匹配。修饰符可以添加到域名，例如，field_gt=42意思就是field大于42。更多细节查看API spec。

排序

大多数的collections在服务端通过HTTP的查询参数按照通用域进行排序.sortLinks表将显示哪些排序是可用的，连同显示已经按照该方式排序的collection的URL.如果指定的话，它也将包含当前回应是以何种方式排序的信息。

分页

API回应默认以每页100资源的限制进行分页.可以通过添加limit=1000查询参数来将上限提升到1000. collection回应中的pagination会告诉你是否收到全部结果；如果没有收到全部结果，将会有一个链接指向下一页。

WebSockets

一些Rancher特性，比如容器日志，shell访问，统计都使用websockets来传输信息流。通过API来使用：

• 点击适当的链接或者执行适当的动作
• 回应将包含一个URL(以ws://或者wss://开头)以及一段长的token字符串.
• 打开一个指向返回URL的WebSocket客户端
• token是由Rancher server签名的，允许所在的主机容器授权这次请求，所以它作为一个HTTP的头部，如Authorization: Bearer <token_string>，发送给Rancher server。
• 如果你通过web浏览器发送请求，你不能发送包容任意HTTP头部的请求，因此你可以选择的是将token添加到URL中作为URL查询参数来代替，如token=<token_string>。