蓝图: https://blueprints.launchpad.net/solum/+spec/api

提议人: Adrian Otto

评论请见此处: https://etherpad.openstack.org/p/solum-api-spec-review

API

概要

动词	URI	描述
GET	/	获取根 `Platform` 资源

GET	/assemblies	获取此租户的 `assembly` 资源列表
POST	/assemblies	创建新的 `assembly` 资源
GET	/assemblies/{id}	获取特定的 `assembly` 资源
PUT	/assemblies/{id}	更新完整的 `assembly` 资源
PATCH	/assemblies/{id}	更新 `assembly` 资源的选定属性
DELETE	/assemblies/{id}	删除此 `assembly` 资源。

GET	/plans	获取此租户的 `plan` 资源列表
POST	/plans	创建新的 `plan` 资源
GET	/plans/{id}	获取特定的 `plan` 资源
PUT	/plans/{id}	更新完整的 `plan` 资源
PATCH	/plans/{id}	更新 `plan` 资源的选定属性
DELETE	/plans/{id}	删除此 `plan` 资源。

GET	/components	获取此租户的 `component` 资源列表
POST	/components	创建新的 `component` 资源
GET	/components/{id}	获取特定的 `component` 资源
PUT	/components/{id}	更新完整的 `component` 资源
PATCH	/components/{id}	更新 `component` 资源的选定属性
DELETE	/components/{id}	删除此 `component` 资源。

GET	/services	获取此租户的 `service` 资源列表
POST	/services	创建新的 `service` 资源
GET	/services/{id}	获取特定的 `service` 资源
PUT	/services/{id}	更新完整的 `service` 资源
PATCH	/services/{id}	更新 `service` 资源的选定属性
DELETE	/services/{id}	删除此 `service` 资源。

GET	/extensions	获取此租户的 `extension` 资源列表
GET	/extensions/{id}	获取特定的 `extension` 资源

API 概念

本节概述了 API 的不同方面以及它们所代表的含义。另请参阅：带有概念图的定义。

基础

角色

提供商

向其客户提供托管平台服务的组织。

消费者

使用托管平台的个人客户。

平台

platform 资源是根级别资源，指代此租户拥有的所有其他资源。此资源用于提供 API 自省。

assembly（组件集合）

assembly 资源表示构成正在运行的应用程序实例的一组组件。您可以随意将其称为“应用程序”，但我们将其称为 assembly，因为大多数云应用程序实际上是由多个服务实例组成的系统。例如，一个三层 Web 应用程序可能有一个负载均衡器组件、一组应用服务器和一个数据库服务器，所有这些都表示为构成 assembly 资源的 component 资源。一个 assembly 资源至少关联一个 component 资源。

plan（计划）

计划资源用于创建 assembly 资源。一个 plan 资源可以重复用于创建任意数量的 assembly 实例。我们可以完全跳过 plan 的概念，只使用 assemblies，并传入计划文件。这只会使创建额外的 assemblies 速度稍慢，这在您真正想要创建大量 assemblies 或希望它们启动非常快的使用场景中可能会很麻烦。

组件

component 资源表示应用程序所需 assembly 的一部分。例如，数据库服务实例可以是 component。component 资源也可以表示静态工件，例如包含用于初始化应用程序的数据的存档文件。一个 assembly 可以有代表不同运行进程的不同组件。例如，您可能有一个 component 表示 API 服务进程，另一个表示使用该 API 服务的 Web UI 进程。最简单的情况是 assembly 只有一个组件。例如，您的组件可能名为“PHP”，并引用平台为运行 PHP 应用程序提供的 PHP service。

service

service 资源表示由 Platform 提供者提供的网络服务。您可以创建引用 service 资源的 component 资源。component 表示 service 的一个实例。您的应用程序可以通过网络远程使用该服务，component 是它获取如何连接的线索（例如定义连接 URL 的属性）的方式。在这种用法中，component 是在其他地方（由另一个应用程序或由 Platform 提供者）提供的服务的虚拟表示。例如，Platform 可能提供一个名为“mysql”的默认 service。您可以创建多个引用“mysql”服务不同实例的 component 资源。每个 component 可以代表 Platform 为给定 assembly 提供的 MySQL 数据库（可能是逻辑数据库）服务的某个多租户实例。

高级

extension（扩展）

extension 资源表示提供者在 Solum 默认提供的功能之外添加到平台上的更改。这可能包括额外的协议语义、资源类型、应用程序生命周期状态等。只要不与 Solum 提供的基本功能相矛盾，任何内容都可以添加。

operation（操作）

operation 资源表示可以对资源执行的操作。操作可以添加到 assembly、component 或 service 资源中。

sensor（传感器）

sensor 资源表示可以从资源收集的动态数据。例如，有关资源（通常是 component）访问速率的统计信息。sensor 资源可以添加到 assembly、component 或 service 资源中。

类型

本节详细介绍了 API 使用的不同数据类型。

数组

JSON 对象的 JSON 数组。例如：伪代码文本 "component[]" 指的是表示为 JSON 对象的组件资源数组。

布尔值

如 JSON [RFC4627] 中所定义，一个字面值为 true 或 false 的标记。

字符串

如 JSON [RFC4627] 中所定义的 UNICODE 字符串。

URI

符合 [RFC3986] 中定义的语法的字符串（见上文）。

协议与资源表示

本节展示了每个资源在 JSON 格式中的表示，以及如何通过 REST API 与它们进行交互。“?” 字符表示该属性是可选的。

无链接。我们将不使用初始 API 设计文档中提议的 Link 或 Link 数组类型。相反，我们将在序列化输出中使用内联对象。例如，一个 assembly 不会包含指向组件的链接，而是包含一个在同一 JSON 中序列化的组件资源数组。我们将此类数组的元素称为“inline-listed-resources”（内联列表资源）。
默认有限视图。为了使结果集的大小易于管理，我们将仅显示 inline-listed-resources 的 *一个* 详细级别。如果需要额外的详细信息，我们可以支持参数来显示可配置的深度级别，直至合理的配置最大值。例如，您可能会看到一个作为 inline-listed-resources 的组件列表，但这些列表不包含它们自己的 inline-listed-resource 列表以用于额外的关系级别。
缩写标签。为了表明给定的内联列出对象如果使用其 URI 加载，可以查询更多详细信息，我们可以添加一个名为“abbreviated”的属性，表示存在当前视图中未显示的额外字段（如果存在且设置为 true）。这样，如果需要该详细信息，可以使用其 URI 单独访问该对象，并且将返回所有详细信息。
分页。为了防止返回不合理大的结果集，Solum 应该有一个可配置的默认显示内联列表对象的最大数量。例如，我们可以在 Solum 配置文件中将该限制设置为 100，当查询包含超过 100 个组件的 Assembly 时，组件列表将作为分页集合提供，就像 ATOM 源一样工作，以便在达到最后一个项目时可以获取下一个项目。

平台

Platform 资源是根级别资源，指代此租户拥有的所有其他资源。Platform 资源用于 API 自省。

动词	URI	描述
GET	/	获取根 `Platform` 资源

{
 "uri": URI,
 "name": String,
 "type": "platform",
 "description": String ?,
 "extensions_uri": "/extensions",
 "implementation_version": String ?,
 "assemblies": assembly[] ?,
 "components": component[] ?,
 "services": service[] ?,
 "parameter_definitions_uri": URI
}

assembly（组件集合）

assembly 资源表示构成正在运行的应用程序实例的一组组件。您可以随意将其称为“应用程序”，但我们将其称为 assembly，因为大多数云应用程序实际上是由多个服务实例组成的系统。例如，一个三层 Web 应用程序可能有一个负载均衡器组件、一组应用服务器和一个数据库服务器，所有这些都表示为构成 assembly 资源的 component 资源。一个 assembly 资源至少关联一个 component 资源。

动词	URI	描述
GET	/assemblies	获取此租户的 `assembly` 资源列表
POST	/assemblies	创建新的 `assembly` 资源
GET	/assemblies/{id}	获取特定的 `assembly` 资源
PUT	/assemblies/{id}	更新完整的 `assembly` 资源
PATCH	/assemblies/{id}	更新 `assembly` 资源的选定属性
DELETE	/assemblies/{id}	删除此 `assembly` 资源。

{
 "uri": URI,
 "name": String,
 "type": "assembly",
 "description": String ?,
 "components": component[] ?,
 "operations_uri": URI ?,
 "sensors_uri": URI ?
}

plan（计划）

plan 资源用于创建 assembly 资源。一个 plan 资源可以重复用于创建任意数量的 assembly 实例。我们可以完全跳过 plan 的概念，只使用 assemblies，并传入计划文件。这只会使创建额外的 assemblies 速度稍慢，这在您真正想要创建大量 assemblies 或希望它们启动非常快的使用场景中可能会很麻烦。

动词	URI	描述
GET	/plans	获取此租户的 `plan` 资源列表
POST	/plans	创建新的 `plan` 资源
GET	/plans/{id}	获取特定的 `plan` 资源
PUT	/plans/{id}	更新完整的 `plan` 资源
PATCH	/plans/{id}	更新 `plan` 资源的选定属性
DELETE	/plans/{id}	删除此 `plan` 资源。

 {
 "name": String ?
 "description": String ?
 "tags": String[] ?
 "camp_version": String
 "origin": String ?
 "artifacts": ArtifactSpecification[] ?
 "services": ServiceSpecification[] ?
}

请注意，ArtifactSpecification 和 ServiceSpecification 将在单独的蓝图和规范中详细说明，该规范描述了将用于生成计划资源的计划文件。创建后将在此处链接。

组件

component 资源表示应用程序所需 assembly 的一部分。例如，数据库服务实例可以是 component。component 资源也可以表示静态工件，例如包含用于初始化应用程序的数据的存档文件。一个 assembly 可以有代表不同运行进程的不同组件。例如，您可能有一个 component 表示 API 服务进程，另一个表示使用该 API 服务的 Web UI 进程。最简单的情况是 assembly 只有一个组件。例如，您的组件可能名为“PHP”，并引用平台为运行 PHP 应用程序提供的 PHP service。

动词	URI	描述
GET	/components	获取此租户的 `component` 资源列表
POST	/components	创建新的 `component` 资源
GET	/components/{id}	获取特定的 `component` 资源
PUT	/components/{id}	更新完整的 `component` 资源
PATCH	/components/{id}	更新 `component` 资源的选定属性
DELETE	/components/{id}	删除此 `component` 资源。

{
 "uri": URI,
 "name": String,
 "type": "component",
 "description": String ?,
 "tags": String[] ?,
 "assembles": assembly[],
 "components": component[] ?,
 "services": service[] ?,
 "operations_uri": URI ?,
 "sensors_uri": URI ?
}

service

service 资源表示由 Platform 提供者提供的网络服务。您可以创建引用 service 资源的 component 资源。component 表示 service 的一个实例。您的应用程序使用网络协议连接到该组件。例如，Platform 可能提供一个名为“mysql”的默认 service。您可以创建多个引用“mysql”服务不同实例的 component 资源。每个 component 可以是 Platform 为给定 assembly 提供的 MySQL 数据库（可能是逻辑数据库）服务的某个多租户实例。

服务资源集合

动词	URI	描述
GET	/services	获取此租户的 `service` 资源列表
POST	/services	创建新的 `service` 资源

复数表示（列表）

Request: GET /services ...
Response:
{
 "uri": URI,
 "name": String,
 "type": "services",
 "description": String, ?
 "services": service[]
}

单个服务资源

GET	/services/{id}	获取特定的 `service` 资源
PUT	/services/{id}	更新完整的 `service` 资源（受访问控制规则约束）
PATCH	/services/{id}	更新 `service` 资源的选定属性（受访问控制规则约束）
DELETE	/services/{id}	删除此 `service` 资源。（受访问控制规则约束）

单数表示

Request: GET /service/{id} ...
Response:
{
 "uri": URI,
 "name": String,
 "type": "service",
 "description": String ?,
 "tags": String[] ?,
 "operations_uri": URI ?,
 "sensors_uri": URI ?,
 "read_only": Boolean
}

注意：Solum 禁止对作为提供者提供的基本配置的一部分的 services 执行 PUT、PATCH 和 DELETE 调用。在这种情况下，readOnly 属性将设置为 TRUE。租户添加的任何 service 资源都将具有设置为 FALSE 的 readOnly 属性，并且可以由同一租户修改或删除。

extension（扩展）

extension 资源表示提供者在 Solum 默认提供的功能之外添加到平台上的更改。这可能包括额外的协议语义、资源类型、应用程序生命周期状态、资源属性等。只要不与 Solum 提供的基本功能相矛盾，任何内容都可以添加。

扩展资源集合

动词	URI	描述
GET	/extensions	获取此租户的 `extension` 资源列表

复数表示（列表）

{
 "uri": URI,
 "name": String,
 "type": "extensions",
 "description": String, ?
 "extensions": extension[]
}

单个扩展资源

动词	URI	描述
GET	/extensions/{id}	获取特定的 `extension` 资源

单数表示

{
 "uri": URI,
 "name": String,
 "type": "extension",
 "description": String,
 "version": String,
 "documentation": URI ?
}

operation（操作）

operation 资源表示目标资源上可用的操作或动作。这用于定义可能更改其相关资源状态的动作。例如，API 已经提供了注册、启动和停止应用程序的方法（POST assembly 进行注册+启动，DELETE assembly 进行停止），但操作提供了一种扩展系统的方法，以添加您自己的动作，例如“暂停”和“恢复”，或“scale_up”和“scale_down”。它具有以下表示

操作资源集合

动词	URI	描述
GET	/operations	获取此租户的 `operation` 资源列表
POST	/operations	创建新的 `operation` 资源

复数表示（列表）

Request: GET /operations ...
Response:
{
 "uri": URI,
 "name": String,
 "type": "operations",
 "description": String ?,
 "target_resource": URI,
 "operations": operation[]
}

单个操作资源

动词	URI	描述
GET	/operations/{id}	获取特定的 `operation` 资源
PUT	/operations/{id}	更新完整的 `operation` 资源
PATCH	/operations/{id}	更新 `operation` 资源的属性
DELETE	/operations/{id}	删除特定的 `operation` 资源

单数表示

Request: GET /operations/{id} ...
Response:
{
 "uri": URI,
 "name": String,
 "type": "operation",
 "description": String ?,
 "documentation": URI,
 "targetResource": URI
}

请注意，documentation 属性是链接到（可能是 PDF）文档，解释您正在定义的操作的语义。这是一种允许 API 扩展的轻量级方法，无需标记语言。

sensor（传感器）

sensor 资源表示一个或多个资源上支持的恰好一个传感器。sensor 资源表示有关资源的动态数据，例如指标或状态。sensor 资源对于公开快速变化的数据或可能需要从辅助系统获取的数据很有用。它具有以下表示

传感器资源集合

动词	URI	描述
GET	/sensors	获取此租户的 `sensor` 资源列表
POST	/sensors	创建新的 `sensor` 资源

复数表示（列表）

Request: GET /sensors ...
Response:
{
 "uri": URI,
 "name": String,
 "type": "sensors",
 "description": String ?,
 "target_resource": URI,
 "sensors": sensor[]
}

单个传感器资源

动词	URI	描述
GET	/sensors/{id}	获取特定的 `sensor` 资源
PUT	/sensors/{id}	更新完整的 `sensor` 资源
PATCH	/sensors/{id}	更新 `sensor` 资源的属性
DELETE	/sensors/{id}	删除特定的 `sensor` 资源

单数表示

Request: GET /sensors/{id} ...
Response:
{
 "uri": URI,
 "name": String,
 "type": "sensor",
 "description": String ?,
 "documentation": URI,
 "target_resource": URI,
 "sensor_type": String,
 "value": <sensor_type> ?,
 "timestamp": Timestamp ?,
 "operations_uri": URI ?
}

Solum/API

目录

API

概要

API 概念

基础

角色

提供商

消费者

平台

assembly（组件集合）

plan（计划）

组件

service

高级

extension（扩展）

operation（操作）

sensor（传感器）

类型

数组

布尔值

字符串

URI

协议与资源表示

平台

assembly（组件集合）

plan（计划）

组件

service

服务资源集合

单个服务资源

extension（扩展）

扩展资源集合

单个扩展资源

operation（操作）

操作资源集合

单个操作资源

sensor（传感器）

传感器资源集合

单个传感器资源