目录：
1. Nova中的几个重要的概念
2. 关于serve的详细说明
3. 关于认证
4. 关于错误
5. 关于limits
6. 资源引用和连接
7. Microversions
8. Paginated collections
9. Efficient polling with the Changes-Since parameter：使用Changes-Since参数的高效polling操作
10. Request and response formats：请求-响应的格式
11. 关于user
12. 关于version
13.
[TOC]

Nova中的几个重要的概念：

（1）server：Instance，可以是虚拟机实例或是物理机或是计算机系统中的容器。server必须是命名的。
在openstack compute API中，server就是一个虚拟机实例，物理机或是一个容器。


（2）Flavor：一个虚拟硬件配置模块，配置包括：磁盘，内存，CPU时间分配优先级等。

（3）Flavor Extra Specs：

（4）Image：一个文件的集合，用来create或是rebuild server的。系统提供一些了预编译的OS镜像。你也可创建自己的特定的镜像。

（5）Key Pair ：ssh或是x509 keypair，可在server boot time注入到server中。

（6）Volume：nova用来做持久化存储的块存储设备。当server创建时，会分配一定的磁盘空间，但是该存储空间是临时的，非持久化的。当server销毁时，该空间会被回收。

（7）Quotas ：tenant可使用的资源的最大值，可用来限制tenant创建的server数目，使用的磁盘空间量。对Quotas修改需要administrator权限。

（8）Rate Limiting ：

（9）Availability zone ：host machine集合，用来控制新的server创建位置。该概念是用来描述server的物理位置。该设置不是必须的（一般用于容灾，如你将server分配在不同的Availability zone，当某一个Avalilability zone(如某一个机架）断电，其他的server还可用，因为处于不同的zone中）

（10）网络方法 ：Port，Floating IPs, Pools ，DNS，Security Groups，Cloudpipe，Extended Networks

以下是关于Services方法的：
（11）Services ：由nova组件提供。通常，nova组件提供运行控制节点或是计算节点上的某个进程内，向外提供服务。可以是面向终端用户的，例如compute rest api service.但是大多数是用来和其他nova service组件通信的。每个service的状态都被监控。如果某个service不能正常响应，则Nova会更新它的状态，使得不会有请求发送到service上。

（12）nova-osapi_compute ：为终端用户或是应用客户端提供 OpenStack Compute REST API，

（13）nova-metadata ：为servers提供OpenStack Metadata API，用来配置运行的servers.

（14）nova-scheduler ：通过追踪资源使用情况，提供完成request的最佳的host。（ This service provides compute request scheduling by tracking available  resources, and finding the host that can best fulfill the request）

（15）nova-conductor：提供数据库访问和其他Openstack服务方法，处理不同版本的服务的兼容性问题，同时处理需要长时间处理的情况，如instance在线迁移等。

（16）nova-compute ：运行在每个计算节点上。该服务和hypervisor通信，管理该节点上的计算资源。

（17）nova-network：该服务处于虚拟server上的网路管理，目前该模块以不再维护，被Neutron取代。

（18）nova-ec2 ：deprecated

（19）nova-consoleauth：该服务为计算实例控制台提供认证服务。

（20）nova-cert ：管理X509证书

（21）Services Actions ：
    enable, disable, disable-log-reason：服务可以被禁用（表明该服务不可用）。一般，管理员在做维护时会禁用服务，例如，当管理员想要对某个计算节点做维护，则可以禁用该节点上的compute service（禁用之后，nova不会分配计算请求到该节点上）。管理员也可以添加注释，表明禁用的原因。
    forced-down ： 立刻将服务置于down状态。事实上，Nova只监控服务的健康状态，这并不保证云架构中的其他设施是否正常，例如数据网络，存储网络或是其他组件。设施中的其他情况的健康监控由外部系统提供。

（22）Hosts ：host是为虚拟server提供资源的物理机。物理机上运行hypervisor，用来提供虚拟server的创建和管理功能。host也运行Nova compute service,用来接收Nova请求，并和该host上的server进行交互。当compute service收到Nova请求后，host会调用hypervisor的driver的某个方法来处理该请求。这里，driver充当一个翻译器，将Nova请求翻译成特定的hypervisor方法调用。Host会向Nova报告自己的状态（这些状态由scheduler服务追踪管理，在scheduler处理一个新建虚拟机示例时，会根据这些数据，选择最合适的host）

（23）Host Actions：host action是指会影响物理机器的动作（不同于那些只会影响运行在该host上的虚拟server的动作）。Nova支持三种电源动作（启动，关机，重启），支持两种状态动作（启动/禁用host,设置host进入或退出维护状态）。当然，这些这些host动作会影响到该host上的serve,因此，在执行这些动作前，需要考虑serve的状态而做出相应的处理。例如，当你想要执行host关机动作，则你可能需要在host关机前，将该host上的serve迁移到其他主机上，这样，这些虚拟server才能无间断的提供服务。
（24）Hypervisors ：hypervisor或是VMM(virtual machine monitor)是一种计算机软件、固件或是硬件，用来创建管理虚拟机的。在Nova中，每个host上都运行一个hypervisor。管理员可通过hypervisor查询虚拟serve的运行状态等。例如，查询正在运行中的虚拟serve,或是serve的CPU,内存，磁盘配置等。目前，nova-compute支持Ironic,LXC,这些技术不需要hypervisor.
（25）Aggregates ：和avalibity zone类似的一个概念，这是这是一种逻辑功能的上的划分。 http://docs.openstack.org/developer/nova/aggregates.html
（26）Migrations ：将server从一台host上搬到另一台host上。管理员可在数据库中查询迁移记录。
（27）Certificates：nova-cert管理X509证书，该证书用于euca-bundle-image。
（28）Volume API ：Cinder's API

关于serve的详细说明

server status
server具有status属性，表明当前server的状态，可为如下值：
- ACTIVE:

• BUILD: server还没有完成之间的build操作

• DELETED: 被删除了

• ERROR: error

• HARD_REBOOT: 硬重启中。断电关机重启中。

• MIGRATING: 在线迁移中。

• PASSWORD: 密码被重置了

• PAUSED: paused.

• REBOOT: soft 重启中

• REBUILD: 正在从镜像从重建。

• RESCUE: server处于rescue 模式中.

• RESIZE: Server is performing the differential copy of data that
  changed during its initial copy. Server is down for this stage.

• REVERT_RESIZE: resize或是迁移失败，目标server被清理，原来的serve被重启。

• SHELVED: 处于shelved状态。处于该状态的server，会根据shelve offload time 配置，自动变成 Shelved_offLoaded状态。

• SHELVED_OFFLOADED: 该处于shelved状态下的served状态下的server已经从host中删除了。

• SHUTOFF: 关机。用户通过非openstack compute api的方式将server 关机，例如用法发出了舒坦down -h的命令。当openstack computer manager检测到vm处于关机状态下时，会将该server的状态变成shutofff.

  shutdown_terminate数据库中实例模型中的一个域。

• SOFT_DELETED: server被标记为deleted，但是还会在云中停留一段时间（该时间可配置）。处于soft deleted状态的server, 授权用户可以恢复该server的状态。但是当滞留期过了，则server会被永久性删除。

• SUSPENDED: 只对 XenServer/XCP, KVM, and ESXi hypervisor有效。

• UNKNOWN: unknow

• VERIFY_RESIZE: server执行了move或是resize操作，等待操作确认中。

HostId
server有host Id属性，记录该server在那个host上。每个帐号下的server具有不同的hostID（不同的host的化）,但不是全局唯一的note:: HostId is unique per account and is not globally unique。

server创建
创建server的过程是异步的。操作完成的快慢由多个因素决定：镜像的位置，网络IO，host负载情况和 使用的flavor 。可通过Get情况对进度查询，请求格式为：/servers/id，该请求返回一个操作完成属性（from 0% to 100% complete）。对于创建server的请求，它的响应会返回：server ID，资源链接，管理密码，这三个属性一定包涵在响应里，但是，其他信息不保证是否一定会返回。你可以通过后续的Get操作获取Server的其他信息。

Server 查询
用户可通过查询选项会查询结果进行过滤。
普通用户可以使用的查询选项有：reservation_id, name, status, image,flavor, ip, changes-since, “ip6 (microversion 2.5)。

对于管理员，除了上述选项外，还可用：all_tenants 选项返回所有tenant的server(默认情况下，只返回当前tenant所拥有的server).

查询实例：
假如 GET /servers/detail 的响应如下：

Response:

   {
       "servers": [
           {
               "name": "test1",
               "OS-EXT-SRV-ATTR:host": "devstack"
               ...
           },
           {
               "name": "t2",
               "OS-EXT-SRV-ATTR:host": "devstack1"
               ...
           },
           {
               "name": "test3",
               "OS-EXT-SRV-ATTR:host": "devstack1"
               ...
           }
       ]
   }

则对于请求 GET /servers/detail?host=devstack1&name=test，可获得如下响应：

 Response:

   {
       "servers": [
           {
               "name": "test3",
               "OS-EXT-SRV-ATTR:host": "devstack1"
               ...
           }
       ]
   }

，
Server actions
server的动作有：
（1）Reboot重启：包括软重启和硬重启。在软重启时，操作系统会发出重启信号，让所有的进程可以保存好状态。硬重启相当于断电重启。
（2）Rebuild 重建：移除server上的所以数据，重新使用镜像代替。但是server ID，ip地址保持不变。
（3）Evacuate :不再报告自己的状态时， nova -compute 服务就相当于下线了。这意味着它会一直处于Active 状态。 Evacuate就是为了处理这种情况的，让管理员强制在另一个host上，reBuild 该server。这不保证该host 之后处于down状态中，所以，这部分工作需要部署人员处理。
（4）resize :改变server的flavor。原来的server会保存一段时间，用于发生错误时，进行回滚。所有的resize操作都需要测试并显示的确认。在确认后，老的server就会被删除。在24小时内，如果没有进行确认，则会自动的进行确认。

在确认后，旧的server被删除，新的server开始提供服务。相反，Revert resize动作会删除新的server,撤销所有的改变。

另外，系统中有一个周期性任务（用resize_confirm_window(in seconds)参数配置）,如果该值不为 0,则 nova compute 会吧处于resize状态 时间 >resize_confirm_window 该值的 server删除。

（5） pause,uppause : 通过发出pause请求，可将server置于暂停状态。该请求会将VM的状态存在RAM中。处于Pause的server会在frozen state状态下运行。

（6）Suspend ，Resume ：当某个server 上的请求不是很多或是server需要做维护时，管理员可能会将某个server置于suspend状态。当suspend某个server，该vm的状态，内存数据会写入到磁盘中，然后该server 会停止。suspend 一个server等同于将某个设备置于冬眠中，该server占用的内存和vCPU可分配给其他的新的server。

（7）Snapshot : 将server的根磁盘状态保存，然后上传到glance镜像库中。之后server可从该镜像boot up.

（8）Backup : 将server的当权状态存储在glance库中，同时将之间老的镜像删除（根据daily,weekly类型）

（9）Start ：Power on
（10）Stop: Power off
（11）Delete，Restore ：关闭server,然后释放所有关联的资源（例如网络资源，卷资源）然后删除该server。
配置参数reclaim_instance_interval（in seconds）可决定 被删除的server 是否还存在系统中。如果该参数值大于0，则被删除的server不会里面被删除，而是将该server放到被删除队列中，直到停留时间大于该参数值时，才会被真正删除。管理员可使用restore操作将在deleted queue中的server恢复。

（12）Shelve ，Shelve offload，Unshelve ：将server shelving意味这在一段时间内不会用到该server，因此hypervisor会暂时的将该server删除。这会将该server的资源空出来给提前的server使用。

默认情况下，shelved_offload_time选项为0，则hypervisor会立马将置为shelved状态的server删除。同上面的参数一样，如果该参数值不为0，则会保留一段时间（这会使得unshelve操作非常快，也可防止误操作）。将shelved server删除的操作是由一个周期性任务完成的。

shelve 操作会首先将server关机，然后对该server做快照（如果该server是从镜像中启动的话）。之后该server的资源会被回收，该server会处于offload。

（13）Lock ，Unlock ：锁住server,则之后该server上不允许进行任何操作。这只能由管理员或是 server拥有者发出。另外，管理员可以重写拥有者上的锁。

（14）Rescue，Unrescue ：从某个特定的地方启动server（用来恢复guest system）

（15）Set administrator password ：设置root/administrator密码。

（16）Migrate ，Live migrate ：迁移通常由管理员发出。该动作会将server从一台host上迁移到另一台host上。在迁移过程中，server会被关机，然后在另一台机器上启动。

在线迁移和迁移类似，只是迁移过程中，不用将server关机。

（17）Trigger crash dump ：dump内存数据，然后重启内核。

Server passwords
在创建server时，可通过adminPass参数指定serve的密码。密码必须满足openStack compute provider的密码复杂性要求。 当密码复杂性不满足 要求时，会导致server进入error状态。在这种情况下，可通过修改密码动作来改变密码。

如果没有指定密码，最会使用一个随机参数的字符串当成密码，该密码会在response中返回（为了安全性起见，密码不应通过get请求返回）

Server metadata
在启动是，可提供自定义的server metadata。metadata 的key -value对最大长度为255字节。key-value对最大个数由maxServerMeta 决定

Recover from a failed compute host
compute host可能会发生异常。该种情况虽然发生概率较低，但是当发生时，运行在该host上的server可能会丢失。在这种情况下，操作人员应用触发evacuate 动作在其他host上创建server.

在异步通信系统中，错误检测不可能做到的。通常，当某个host被认为出现异常后，应该就将该host从云中隔离，该host上的server上关联的存储，网络应该和该host隔离。这些动作被称为“fencing the host”，但是这些动作的实现不是nova考虑的范围内。

当某个host被隔离时，该host上的server应该在其他的host上重建。重建时，需要注意的是需要保证之前的实例不会重新出现（如坏的host又好了，这就会出现两个相同的server竞争资源了）

需要注意的是：重建过程可能会导致用户server数据的丢失。因为之前的server已经无法访问，如果老的server有数据存在局部磁盘中，则这些数据就会丢失。Evacuate和rebuild执行的操作相同，从glance上下载镜像，然后创建一个临时的磁盘。对于卷存储或是共享存储会重新链接。这些存储数据不会损失（这也是fencing 操作非常重要的原因，可以防止两个server同时访问这些资源，造成数据丢失）

User resizes server to get more resources
可能存在一种情况，用户想改变server的flavor，例如改变cpu数，磁盘资源数等。这通过使用新的flavor重启server实现。可能新的server会被调度到另外一个host上去。
resize操作需要执行：server关机，查找一个新的适合的host ，将server的移动到新的host上去，启动新的server。在resize操作后，用户需要对resize操作进行确认。确认操作会导致原先的server的删除。另外，用户也可调用Revert resize来删除新建的server而保留老的server。如果用户没有确认，则系统会自动的进行确认。

User doesn’t want to be charged when not using a server
有时，用户可能有很长一段时间不使用server，但是仅仅对这些server执行关机动作并不会释放server所拥有的资源（也就是说，用户还是需要对这段时间对这些server付费）。但是执行shelve操作可以让server释放资源，因此，这为“用户长时间不使用server时，不需要付费”这个需求提供了可行的解决方案。

需要注意的是，shelve操作会影响server的可用性（因为处于shelved状态下的server，在一段时间后，会变成offload，在系统中删除，当用户执行unshelved操作时，可变成正常状态，但是需要重新构建启动）。

User data
在metadata service中，用户数据文件是一个特殊的key。Nova支持两种方式来将用户数据发送到部署的server上：1，通过metadata service，使用预先定义的ip地址（169.254.169.254）进行访问；2，通过一个预先定义的driver,将metadata包装成iso9660或是vfat格式的磁盘，这样，部署的server可以通过cloud-init引擎或是其他的引擎来boot阶段访问这些数据。

Server personality
你可以通过向文件系统中注入数据来达到定制server的目的。当注入数据时，你需要遵从如下原则：
（1）文件路径数据的最大值是255(文件路径不能太长）
（2）使用Base64格式编码文件内容。文件内容的最大值根据compute provider配置不同而不同，同时和server image有关。

关于认证

1.Each HTTP request against the OpenStack Compute system requires the inclusion of specific authentication credentials.
2.A single deployment may support multiple authentication schemes (OAuth, Basic Auth, Token).

关于错误

1.Every HTTP request has a status code.Tracking Errors by Request ID.每个request都有一个唯一的request ID,该ID包涵在response header中。对于终端用户来说，可通过API列出server Action的结果，通过request id查询request action.
更多细节见：http://developer.openstack.org/api-ref/compute/#servers-run-an-action-servers-action.
2.所有的东西都记录在log中，包括request id.这帮助管理员追踪API 请求处理情况。
3.同步错误：在response中，当返回非2XX的状态码时，都表明发生了错误，返回的response形如：

    .. code::
        {
             "itemNotFound":{
            "code": 404,
            "message":"Aggregate agg_h1 could not be found."
        }
    }

关于错误码的具体细节，见：http://specs.openstack.org/openstack/api-wg/guidelines/http.html#http-response-codes

4.异步错误：当server处于ERROR状态时，对于某些操作，如resize,可能发生如下情况：操作失败，但是实例instance正确的恢复到操作前的状态。在这种情况下，你可上述的Server Action API中了解到更多情况。当serve处于error状态时，会返回一个异常信息。返回格式和通过错误格式相同。
例如：Example:Server in error state: JSON response**

.. code::

    {
        "server": {
            "id": "52415800-8b69-11e0-9b19-734f0000ffff",
            "tenant_id": "1234",
            "user_id": "5678",
            "name": "sample-server",
            "created": "2010-08-10T12:00:00Z",
            "hostId": "e4d909c290d0fb1ca068ffafff22cbd0",
            "status": "ERROR",
            "progress": 66,
            "image" : {
                "id": "52415800-8b69-11e0-9b19-734f6f007777"
            },
            "flavor" : {
                "id": "52415800-8b69-11e0-9b19-734f216543fd"
            },
            "fault" : {
                "code" : 500,
                "created": "2010-08-10T11:59:59Z",
                "message": "No valid host was found. There are not enough hosts available.",
                "details": [snip]
            },
            "links": [
                {
                    "rel": "self",
                    "href": "http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f000004d2"
                },
                {
                    "rel": "bookmark",
                    "href": "http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734f000004d2"
                }
            ]
        }
    }

关于limits

每个帐号可以提前配置该帐号可使用的资源限额。限额可通过两种方式配置。
（1）绝对限额：绝对限额通过name/value的形式指定。一个配置的例子如下：

Table: Sample absolute limits

+——————-+——————-+————————————+
| Name | Value | Description |
+——————-+——————-+————————————+
| maxTotalRAMSize | 51200 | Maximum total amount of RAM (MB) |
+——————-+——————-+————————————+
| maxServerMeta | 5 | Maximum number of metadata items |
| | | associated with a server. |
+——————-+——————-+————————————+
| maxImageMeta | 5 | Maximum number of metadata items |
| | | associated with an image. |
+——————-+——————-+————————————+
| maxPersonality | 5 | The maximum number of file |
| | | path/content pairs that can be |
| | | supplied on server build. |
+——————-+——————-+————————————+
| maxPersonalitySize| 10240 | The maximum size, in bytes, for |
| | | each personality file. |
+——————-+——————-+————————————+

（2）通过编程决定限额
应用可通过编程来决定当前帐号的限额。

更多信息见：https://developer.openstack.org/api-ref/compute/#limits-limits

资源引用和连接

通常情况下，某个资源需要引用其他的资源，例如，当创建一个虚拟机时，你需要指明创建该虚拟机所用的镜像。你可以通过ID或是URL的形式指明该镜像。当使用ID时，则说明该镜像存在当前的部署中。
一个ID镜像引用的例子（Json request）

.. code::

    {
       "server":{
          "flavorRef":"http://openstack.example.com/openstack/flavors/1",
          "imageRef":"http://openstack.example.com/openstack/images/70a599e0-31e7-49b7-b260-868f441e862b",
          "metadata":{
             "My Server Name":"Apache1"
          },
          "name":"new-server-test",
          "personality":[
             {
                "contents":"ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA==",
                "path":"/etc/banner.txt"
             }
          ]
       }
    }

Example: Full image reference: JSON request

.. code::

    {
        "server": {
            "name": "server-test-1",
            "imageRef": "b5660a6e-4b46-4be3-9707-6b47221b454f",
            "flavorRef": "2",
            "max_count": 1,
            "min_count": 1,
            "networks": [
                {
                    "uuid": "d32019d3-bc6e-4319-9c1d-6722fc136a22"
                }
            ],
            "security_groups": [
                {
                    "name": "default"
                },
                {
                    "name": "another-secgroup-name"
                }
            ]
        }
    }

为了方便起见，资源可以包含指向自己的链接。资源可以有如下几种绑定的连接
（1）self链接： contains a versioned link to the resource. Use these links when the link is followed immediately.

.. code::

    {
       "server":{
          "id":"52415800-8b69-11e0-9b19-734fcece0043",
          "name":"my-server",
          "links":[
             {
                "rel":"self",
                "href":"http://servers.api.openstack.org/v2.1/servers/52415800-8b69-11e0-9b19-734fcece0043"
             },
             {
                "rel":"bookmark",
                "href":"http://servers.api.openstack.org/servers/52415800-8b69-11e0-9b19-734fcece0043"
             }
          ]
       }
    }

（2）bookmark 链接 :provides a permanent link to a resource that is appropriate for long term storage.

（3）alternate 链接 : can contain an alternate representation of the resource. For example, an OpenStack Compute image might have an alternate representation in the OpenStack Image service.

.. code::

    {
        "image" : {
            "id" : "52415800-8b69-11e0-9b19-734f5736d2a2",
            "name" : "My Server Backup",
            "links": [
                {
                    "rel" : "self",
                    "href" : "http://servers.api.openstack.org/v2.1/images/52415800-8b69-11e0-9b19-734f5736d2a2"
                },
                {
                    "rel" : "bookmark",
                    "href" : "http://servers.api.openstack.org/images/52415800-8b69-11e0-9b19-734f5736d2a2"
                },
                {
                    "rel"  : "alternate",
                    "type" : "application/vnd.openstack.image",
                    "href" : "http://glance.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
                }
            ]
        }
    }

Microversions

Nova API新增了Microversions属性，用来做版本更新记录。用户可以使用Microversions发现新特征。Microversions可用于如下场景：
（1）旧版本的客户端和 新版本的cloud : 在使用老的客户端和newer cloud通信之前，客户端可以检测Microversions的minimum version，验证该云是否和老的API兼容。这可以防止后向的API不兼容。当前的microversions的minimum version为2.1 ，该版本和之前legacy V2 API 兼容。这意味着使用 legacy V2 API 客户化的用户不必担心 云升级之后的不兼容性。
（2）用户发现可用的新特性：可通过microversions发现新特性。用户客户端应该首先检测microversions 。

Version Discovery
可使用Version API获取minimum and maximum Microsoftversion。Requests to ‘/’ will get version info for all endpoints。response的例子如下：

 {
    "versions": [
        {
            "id": "v2.0",
            "links": [
                {
                    "href": "http://openstack.example.com/v2/",
                    "rel": "self"
                }
            ],
            "status": "SUPPORTED",
            "version": "",
            "min_version": "",
            "updated": "2011-01-21T11:33:21Z"
        },

        {
            "id": "v2.1",
            "links": [
                {
                    "href": "http://openstack.example.com/v2.1/",
                    "rel": "self"
                }
            ],
            "status": "CURRENT",
            "version": "2.14",
            "min_version": "2.1",
            "updated": "2013-07-23T11:33:21Z"
        }
    ]
  }

response中的version值为maximum microversion，min_version的值为min_version。如果值为空，则表明endpoint不支持 microversion，这是一个legacy v2 API endpoint，例如例子中的 endpoint http://openstack.example.com/v2/ 。endpoint http://openstack.example.com/v2.1/支持 microversions。

Client Interaction
client通过HTTP头来指明他们想用的API的microversion，例如：X-OpenStack-Nova-API-Version: 2.4。从microversion 2.27版本开始，也可以使用如下HTTP Header : OpenStack-API-Version: compute 2.27。

更多信息见：http://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html

Paginated collections： 集合分页

为了降低service的负担，list操作每次返回的最大记录数是受限的。每次返回的最大记录数由compute provider决定。为了能够在结果集中遍历，可以在URI中设置limit,marker参数，来设置个性化的限制。例如： ?limit=100&marker=1234 。marker参数是上回list操作返回的最后一条记录的ID。默认情况下，service 将记录按照创建时间以降序排序。当service不能确定创建时间字段时，则用ID排序。limit参数设置返回的最大记录数。这两个参数是可选的。当设置的limit参数值操作了系统所支持的最大记录树，则会抛出overLImit错误，错误码为413。当marker 是一个非法的id时，则会返回badRequest错误，错误码为400。

为了方便起见，集合应该返回next link，也可返回previous link(optional。目前，系统支持返回next link，最后一页没有。在下面的例子中，集合包涵三页数据。第一页使用 GET http://servers.api.openstack.org/v2.1/servers?limit=1获取。 这里limit=1。接下来的请求使用上次请求设置的limit。

Example: Servers collection: JSON (first page)

.. code::

    {
       "servers_links":[
          {
             "href":"https://servers.api.openstack.org/v2.1/servers?limit=1&marker=fc45ace4-3398-447b-8ef9-72a22086d775",
             "rel":"next"
          }
       ],
       "servers":[
          {
             "id":"fc55acf4-3398-447b-8ef9-72a42086d775",
             "links":[
                {
                   "href":"https://servers.api.openstack.org/v2.1/servers/fc45ace4-3398-447b-8ef9-72a22086d775",
                   "rel":"self"
                },
                {
                   "href":"https://servers.api.openstack.org/v2.1/servers/fc45ace4-3398-447b-8ef9-72a22086d775",
                   "rel":"bookmark"
                }
             ],
             "name":"elasticsearch-0"
          }
       ]
    }

**Example: Paginated metadata: JSON**

.. code::

    {
        "server": {
            "id": "52415800-8b69-11e0-9b19-734f6f006e54",
            "name": "Elastic",
            "metadata": {
                "Version": "1.3",
                "ServiceType": "Bronze"
            },
            "metadata_links": [
                {
                    "rel": "next",
                    "href": "https://servers.api.openstack.org/v2.1/servers/fc55acf4-3398-447b-8ef9-72a42086d775/meta?marker=ServiceType"
                }
            ],
            "links": [
                {
                    "rel": "self",
                    "href": "https://servers.api.openstack.org/v2.1/servers/fc55acf4-3398-447b-8ef9-72a42086d775"
                }
            ]
        }
    }

Efficient polling with the Changes-Since parameter：使用Changes-Since参数的高效polling操作

Rest API可以通过Get请求来获取某些操作的状态。为了避免在polling间隔内，重新下载，重新解析整个状态，可以使用changes-since参数来获取自从上次请求到这次请求所发生的变化。changes-since的time值使用ISO 8601 dateTime（ISO
8601 http://en.wikipedia.org/wiki/ISO_8601）时区可用±hh:mm的形式追加在后面（hh:mm的值为相对于UTC的偏移）当没有指明时区时，默认使用UTC时区。如果从 changes-since time到现在，没有发生改变，则会返回一个空的列表。如果数据变化了，则只会返回反生变化的条目。例如，执行Get请求 ： https://api.servers.openstack.org/v2.1/servers?\ changes-since\ =2015-01-24T17:08Z ，将会返回在2015年1月24日，17：08：00 UTC之后发生变化了的server列表。

为了追踪变化，changes-since 过滤器可显示“recently”被删除的条目。 images和server都包涵一个“deleted”状态，暗示该资源已被删除。不要求必须实现对删除资源的追踪。因此，获取的的changes-since回复可能会缺少一些删除数据变化记录。

Request and response formats：请求-响应的格式

openStack compute只支持JSON的请求和响应，MIME 类型为application/json。因为支持一种格式，所有的请求响应都被默认为json格式。

一个例子：

**Example: JSON request with headers**

.. code::

   POST /v2.1/servers HTTP/1.1
   Host: servers.api.openstack.org
   X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

.. code:: JSON

    {
        "server": {
            "name": "server-test-1",
            "imageRef": "b5660a6e-4b46-4be3-9707-6b47221b454f",
            "flavorRef": "2",
            "max_count": 1,
            "min_count": 1,
            "networks": [
                {
                    "uuid": "d32019d3-bc6e-4319-9c1d-6722fc136a22"
                }
            ],
            "security_groups": [
                {
                    "name": "default"
                },
                {
                    "name": "another-secgroup-name"
                }
            ]
        }
    }

Users：用户

Compute API 包括终端用户 和管理员的操作 API
（1）基于角色的访问控制 ：Keystone中间件负责认证用户和角色。Compute API使用角色和oslo.policy来决定用户能进行那些操作

（2）用户角色，角色模型：为了容易理解，需要对如下几种角色标准化

• 应用部署人员：通过API直接或简介的创建，删除server
• 应用开发人员：可创建运行在云上的应用，创建镜像
• 云管理员：部署，操作和维护云

实际中的角色比这个可能要复杂的多，如云管理员可分中好几种。

Versions

OpenStack Compute API 支持URI和MIME的version 模式。
（1）URI 版本模式：
在路径前包含目标版本标识符，形如：https://servers.api.openstack.org/
v2.1/…
（2）MIME版本模式：
使用HTTP内容协商，使用Accept 或是Content-Type 字段表明MIME类型。version MIME type跟在base MIME 类型后，例如application/json。如果使用HTTP和URI两种方式声明的版本号冲突，则优先使用URI指定的。

Example: Request with MIME type versioning

.. code::

    GET /214412/images HTTP/1.1
    Host: servers.api.openstack.org
    Accept: application/vnd.openstack.compute.v2.1+json
    X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

Example: Request with URI versioning

.. code::

    GET /v2.1/214412/images HTTP/1.1
    Host: servers.api.openstack.org
    Accept: application/json
    X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

如果请求没有指明API版本，则会返回一个300的response，在response中，包涵所有的可用的version说明。一个多版本的例子如下：

**Example: Multiple choices: JSON response**

.. code::

  {
    "choices": [
        {
            "id": "v2.0",
            "links": [
                {
                    "href": "http://servers.api.openstack.org/v2/7f5b2214547e4e71970e329ccf0b257c/servers/detail",
                    "rel": "self"
                }
            ],
            "media-types": [
                {
                    "base": "application/json",
                    "type": "application/vnd.openstack.compute+json;version=2"
                }
            ],
            "status": "SUPPORTED"
        },
        {
            "id": "v2.1",
            "links": [
                {
                    "href": "http://servers.api.openstack.org/v2.1/7f5b2214547e4e71970e329ccf0b257c/servers/detail",
                    "rel": "self"
                }
            ],
            "media-types": [
                {
                    "base": "application/json",
                    "type": "application/vnd.openstack.compute+json;version=2.1"
                }
            ],
            "status": "CURRENT"
        }
    ]
  }

status值表明了该API当前的状态。current表明是最新的；support表明是老的API，不支持新特性；DEPRECATED表明该API将被移除；
更多信息见：http://developer.openstack.org/api-ref/compute/#api-versions