Merge "Update docs structure according to new guidelines in https://wiki.opnfv.org/display/DOC"

25 files changed, 3428 insertions, 0 deletions

diff --git a/docs/development/requirements/NB_interface.rst b/docs/development/requirements/NB_interface.rst
new file mode 100644
index 0000000..8dba601
--- /dev/null
+++ b/docs/development/requirements/NB_interface.rst
@@ -0,0 +1,1061 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _northbound_API:
+
+Detailed northbound interface specification
+===========================================
+
+.. Note::
+   This is Work in Progress.
+
+ETSI NFV IFA Information Models
+-------------------------------
+
+Compute Flavor
+^^^^^^^^^^^^^^
+
+A compute flavor includes information about number of virtual CPUs, size of
+virtual memory, size of virtual storage, and virtual network interfaces
+[NFVIFA005]_.
+
+.. figure:: images/computeflavor.png
+   :name: computeflavor
+   :width: 90%
+
+Virtualised Compute Resources
+-----------------------------
+
+Compute Capacity Management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Subscribe Compute Capacity Change Event
+"""""""""""""""""""""""""""""""""""""""
+
+Subscription from Consumer to VIM to be notified about compute capacity changes
+
+.. http:post:: /capacity/compute/subscribe
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+       POST /capacity/compute/subscribe HTTP/1.1
+       Accept: application/json
+
+       {
+          "zoneId": "12345",
+          "computeResourceTypeId": "vcInstances",
+          "threshold": {
+             "thresholdType" : "absoluteValue",
+             "threshold": {
+                 "capacity_info": "available",
+                 "condition": "lt",
+                 "value": 5
+             }
+          }
+       }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+       HTTP/1.1 201 CREATED
+       Content-Type: application/json
+
+       {
+          "created": "2015-09-21T00:00:00Z",
+          "capacityChangeSubscriptionId": "abcdef-ghijkl-123456789"
+       }
+
+   :statuscode 400: computeResourceTypeId is missing
+
+Query Compute Capacity for a defined resource type
+""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Request to find out about available, reserved, total and allocated compute
+capacity.
+
+.. http:get:: /capacity/compute/query
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /capacity/compute/query HTTP/1.1
+      Accept: application/json
+
+      {
+        "zoneId": "12345",
+        "computeResourceTypeId": "vcInstances",
+        "timePeriod":  {
+             "startTime": "2015-09-21T00:00:00Z",
+             "stopTime": "2015-09-21T00:05:30Z"
+        }
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+       HTTP/1.1 200 OK
+       Content-Type: application/json
+
+       {
+          "zoneId": "12345",
+          "lastUpdate": "2015-09-21T00:03:20Z",
+          "capacityInformation": {
+             "available": 4,
+             "reserved": 17,
+             "total": 50,
+             "allocated": 29
+          }
+       }
+
+   :query limit: Default is 10.
+   :statuscode 404: resource zone unknown
+
+
+Query Compute Capacity with required attributes
+"""""""""""""""""""""""""""""""""""""""""""""""
+Request to find out available compute capacity with given characteristics
+
+.. http:get:: /capacity/compute/query
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /capacity/compute/query HTTP/1.1
+      Accept: application/json
+
+      {
+        "zoneId": "12345",
+        "resourceCriteria":  {
+             "virtualCPU": {
+                 "cpuArchitecture": "x86",
+                 "numVirtualCpu": 8
+             }
+        },
+        "attributeSelector":  "available",
+        "timePeriod":  {
+             "startTime": "2015-09-21T00:00:00Z",
+             "stopTime": "2015-09-21T00:05:30Z"
+        }
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+       HTTP/1.1 200 OK
+       Content-Type: application/json
+
+       {
+          "zoneId": "12345",
+          "lastUpdate": "2015-09-21T00:03:20Z",
+          "capacityInformation": {
+             "available": 50
+          }
+       }
+
+   :query limit: Default is 10.
+   :statuscode 404: resource zone unknown
+
+Notify Compute Capacity Change Event
+""""""""""""""""""""""""""""""""""""
+
+Notification about compute capacity changes
+
+.. http:post:: /capacity/compute/notification
+   :noindex:
+
+   **Example notification**:
+
+   .. sourcecode:: http
+
+      Content-Type: application/json
+
+      {
+           "zoneId": "12345",
+           "notificationId": "zyxwvu-tsrqpo-987654321",
+           "capacityChangeTime": "2015-09-21T00:03:20Z",
+           "resourceDescriptor": {
+              "computeResourceTypeId": "vcInstances"
+           },
+           "capacityInformation": {
+              "available": 4,
+              "reserved": 17,
+              "total": 50,
+              "allocated": 29
+           }
+      }
+
+Compute Resource Reservation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create Compute Resource Reservation
+"""""""""""""""""""""""""""""""""""
+
+Request the reservation of compute resource capacity
+
+.. http:post:: /reservation/compute/create
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+       POST /reservation/compute/create HTTP/1.1
+       Accept: application/json
+
+       {
+           "startTime": "2015-09-21T01:00:00Z",
+           "computePoolReservation": {
+               "numCpuCores": 20,
+               "numVcInstances": 5,
+               "virtualMemSize": 10
+           }
+       }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+       HTTP/1.1 201 CREATED
+       Content-Type: application/json
+
+       {
+          "reservationData": {
+             "startTime": "2015-09-21T01:00:00Z",
+             "reservationStatus": "initialized",
+             "reservationId": "xxxx-yyyy-zzzz",
+             "computePoolReserved": {
+                 "numCpuCores": 20,
+                 "numVcInstances": 5,
+                 "virtualMemSize": 10,
+                 "zoneId": "23456"
+             }
+          }
+       }
+
+or virtualization containers
+
+.. http:post:: reservation/compute/create
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+       POST /reservation/compute/create HTTP/1.1
+       Accept: application/json
+
+       {
+         "startTime": "2015-10-05T15:00:00Z",
+         "virtualizationContainerReservation": [
+           {
+              "containerId": "myContainer",
+              "containerFlavor": {
+                 "flavorId": "myFlavor",
+                 "virtualCpu": {
+                    "numVirtualCpu": 2,
+                    "cpuArchitecture": "x86"
+                 },
+                 "virtualMemory": {
+                     "numaEnabled": "False",
+                     "virtualMemSize": 16
+                 },
+                 "storageAttributes": {
+                     "typeOfStorage": "volume",
+                     "sizeOfStorage": 16
+                 }
+              }
+           }
+         ]
+       }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+       HTTP/1.1 201 CREATED
+       Content-Type: application/json
+
+       {
+          "reservationData": {
+             "startTime": "2015-10-05T15:00:00Z",
+             "reservationId": "aaaa-bbbb-cccc",
+             "reservationStatus": "initialized",
+             "virtualizationContainerReserved": [
+                 {
+                    "containerId": "myContainer",
+                    "flavorId": "myFlavor",
+                    "virtualCpu": {
+                        "numVirtualCpu": 2,
+                        "cpuArchitecture": "x86"
+                    },
+                    "virtualMemory": {
+                        "numaEnabled": "False",
+                        "virtualMemSize": 16
+                    },
+                    "virtualDisks": {
+                        "storageId": "myStorage",
+                        "flavourId": "myStorageFlavour",
+                        "typeOfStorage": "volume",
+                        "sizeOfStorage": 16,
+                        "operationalState": "enabled"
+                    }
+                 }
+             ]
+          }
+       }
+
+
+
+Query Compute Resource Reservation
+""""""""""""""""""""""""""""""""""
+
+Request to find out about reserved compute resources that the consumer has
+access to.
+
+.. http:get:: /reservation/compute/query
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /reservation/compute/query HTTP/1.1
+      Accept: application/json
+
+      {
+         "queryReservationFilter": [
+             {
+                 "reservationId": "xxxx-yyyy-zzzz"
+             }
+         ]
+
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+       HTTP/1.1 200 OK
+       Content-Type: application/json
+
+       {
+          "queryResult":
+          {
+             "startTime": "2015-09-21T01:00:00Z",
+             "reservationStatus": "active",
+             "reservationId": "xxxx-yyyy-zzzz",
+             "computePoolReserved":
+             {
+                 "numCpuCores": 20,
+                 "numVcInstances": 5,
+                 "virtualMemSize": 10,
+                 "zoneId": "23456"
+             }
+          }
+       }
+
+   :statuscode 404: reservation id unknown
+
+Update Compute Resource Reservation
+"""""""""""""""""""""""""""""""""""
+
+Request to update compute resource reservation
+
+.. http:post:: /reservation/compute/update
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+       POST /reservation/compute/update HTTP/1.1
+       Accept: application/json
+
+       {
+           "startTime": "2015-09-14T16:00:00Z",
+           "reservationId": "xxxx-yyyy-zzzz"
+       }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+       HTTP/1.1 201 CREATED
+       Content-Type: application/json
+
+       {
+         "reservationData": {
+             "startTime": "2015-09-14TT16:00:00Z",
+             "reservationStatus": "active",
+             "reservationId": "xxxx-yyyy-zzzz",
+             "computePoolReserved": {
+                 "numCpuCores": 20,
+                 "numVcInstances": 5,
+                 "virtualMemSize": 10,
+                 "zoneId": "23456"
+             }
+          }
+       }
+
+Terminate Compute Resource Reservation
+""""""""""""""""""""""""""""""""""""""
+
+Request to terminate a compute resource reservation
+
+.. http:delete:: /reservation/compute/(reservation_id)
+   :noindex:
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+       HTTP/1.1 200
+       Content-Type: application/json
+
+       {
+          "reservationId": "xxxx-yyyy-zzzz",
+       }
+
+
+Subscribe Resource Reservation Change Event
+"""""""""""""""""""""""""""""""""""""""""""
+
+Subscription from Consumer to VIM to be notified about changes
+related to a reservation or to the resources associated to it.
+
+.. http:post:: /reservation/subscribe
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+       POST /reservation/subscribe HTTP/1.1
+       Accept: application/json
+
+       {
+          "inputFilter": [
+              {
+                 "reservationId": "xxxx-yyyy-zzzz",
+              }
+          ]
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+       HTTP/1.1 201 CREATED
+       Content-Type: application/json
+
+       {
+          "created": "2015-09-21T00:00:00Z",
+          "reservationChangeSubscriptionId": "abcdef-ghijkl-123456789"
+       }
+
+   :statuscode 400: inputFilter is missing
+
+
+Notify Resource Reservation Change Event
+""""""""""""""""""""""""""""""""""""""""
+
+Notification about changes in a compute resource reservation
+
+.. http:post:: /capacity/compute/notification
+   :noindex:
+
+   **Example notification**:
+
+   .. sourcecode:: http
+
+      Content-Type: application/json
+
+      {
+           "changeId": "aaaaaa-btgxxx-987654321",
+           "reservationId": "xxxx-yyyy-zzzz",
+           "vimId": "vim-CX-03"
+           "changeType": "Reservation time change"
+           "changedReservationData": {
+              "endTime": "2015-10-14TT16:00:00Z",
+           }
+      }
+
+
+
+Virtualised Network Resources
+-----------------------------
+
+Network Capacity Management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Subscribe Network Capacity Change Event
+"""""""""""""""""""""""""""""""""""""""
+
+Susbcription from Consumer to VIM to be notified about network capacity changes
+
+.. http:post:: /capacity/network/subscribe
+    :noindex:
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+        POST /capacity/network/subscribe HTTP/1.1
+        Accept: application/json
+
+        {
+            "networkResourceTypeId": "publicIps",
+            "threshold": {
+               "thresholdType": "absoluteValue",
+               "threshold": {
+                   "capacity_info": "available",
+                   "condition": "lt",
+                   "value": 5
+               }
+            }
+        }
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+        HTTP/1.1 201 CREATED
+        Content-Type: application/json
+
+        {
+           "created": "2015-09-28T00:00:00Z",
+           "capacityChangeSubscriptionId": "bcdefg-hijklm-234567890"
+        }
+
+Query Network Capacity
+""""""""""""""""""""""
+
+Request to find out about available, reserved, total and allocated network
+capacity.
+
+.. http:get:: /capacity/network/query
+    :noindex:
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+        GET /capacity/network/query HTTP/1.1
+        Accept: application/json
+
+        {
+            "networkResourceTypeId": "publicIps",
+            "timePeriod":  {
+                "startTime": "2015-09-28T00:00:00Z",
+                "stopTime": "2015-09-28T00:05:30Z"
+            }
+        }
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Content-Type: application/json
+
+        {
+            "lastUpdate": "2015-09-28T00:02:10Z",
+            "capacityInformation": {
+                "available": 4,
+                "reserved": 10,
+                "total": 64,
+                "allocated": 50
+            }
+        }
+
+Notify Network Capacity Change Event
+""""""""""""""""""""""""""""""""""""
+
+Notification about network capacity changes
+
+.. http:post:: /capacity/network/notification
+    :noindex:
+
+    **Example notification**:
+
+    .. sourcecode:: http
+
+        Content-Type: application/json
+
+        {
+            "notificationId": "yxwvut-srqpon-876543210",
+            "capacityChangeTime": "2015-09-28T00:02:10Z",
+            "resourceDescriptor": {
+                "networkResourceTypeId": "publicIps"
+            },
+            "capacityInformation": {
+                "available": 4,
+                "reserved": 10,
+                "total": 64,
+                "allocated": 50
+            }
+        }
+
+Network Resource Reservation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create Network Resource Reservation
+"""""""""""""""""""""""""""""""""""
+
+Request the reservation of network resource capacity and/or virtual networks,
+network ports
+
+.. http:post:: /reservation/network/create
+    :noindex:
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+        POST /reservation/network/create HTTP/1.1
+        Accept: application/json
+
+        {
+            "startTime": "2015-09-28T01:00:00Z",
+            "networkReservation": {
+                "numPublicIps": 2
+            }
+        }
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+        HTTP/1.1 201 CREATED
+        Content-Type: application/json
+
+        {
+            "reservationData": {
+                "startTime": "2015-09-28T01:00:00Z",
+                "reservationStatus": "initialized",
+                "reservationId": "wwww-xxxx-yyyy",
+                "publicIps": [
+                    "10.2.91.60",
+                    "10.2.91.61"
+                ]
+            }
+        }
+
+Query Network Resource Reservation
+""""""""""""""""""""""""""""""""""
+
+Request to find out about reserved network resources that the consumer has
+access to.
+
+.. http:get:: /reservation/network/query
+    :noindex:
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+        GET /reservation/network/query HTTP/1.1
+        Accept: application/json
+
+        {
+            "queryReservationFilter": [
+                {
+                    "reservationId": "wwww-xxxx-yyyy"
+                }
+            ]
+        }
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+       HTTP/1.1 200 OK
+       Content-Type: application/json
+
+       {
+           "queryResult": {
+               "startTime": "2015-09-28T01:00:00Z",
+               "reservationStatus": "active",
+               "reservationId": "wwww-xxxx-yyyy",
+               "publicIps": [
+                   "10.2.91.60",
+                   "10.2.91.61"
+               ]
+           }
+       }
+
+Update Network Resource Reservation
+"""""""""""""""""""""""""""""""""""
+
+Request to update network resource reservation
+
+.. http:post:: /reservation/network/update
+    :noindex:
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+         POST /reservation/network/update HTTP/1.1
+         Accept: application/json
+
+         {
+             "startTime": "2015-09-21T16:00:00Z",
+             "reservationId": "wwww-xxxx-yyyy"
+         }
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+        HTTP/1.1 201 CREATED
+        Content-Type: application/json
+
+        {
+            "reservationData": {
+                "startTime": "2015-09-21T16:00:00Z",
+                "reservationStatus": "active",
+                "reservationId": "wwww-xxxx-yyyy",
+                "publicIps": [
+                   "10.2.91.60",
+                   "10.2.91.61"
+                ]
+            }
+        }
+
+Terminate Network Resource Reservation
+""""""""""""""""""""""""""""""""""""""
+
+Request to terminate a network resource reservation
+
+.. http:delete:: /reservation/network/(reservation_id)
+   :noindex:
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+       HTTP/1.1 200
+       Content-Type: application/json
+
+       {
+          "reservationId": "xxxx-yyyy-zzzz",
+       }
+
+Virtualised Storage Resources
+-----------------------------
+
+Storage Capacity Management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Subscribe Storage Capacity Change Event
+"""""""""""""""""""""""""""""""""""""""
+
+Subscription from Consumer to VIM to be notified about storage capacity changes
+
+.. http:post:: /capacity/storage/subscribe
+    :noindex:
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+        POST /capacity/storage/subscribe HTTP/1.1
+        Accept: application/json
+
+        {
+           "storageResourceTypeId": "volumes",
+           "threshold": {
+              "thresholdType": "absoluteValue",
+              "threshold": {
+                  "capacity_info": "available",
+                  "condition": "lt",
+                  "value": 3
+               }
+           }
+        }
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+        HTTP/1.1 201 CREATED
+        Content-Type: application/json
+
+        {
+            "created": "2015-09-28T12:00:00Z",
+            "capacityChangeSubscriptionId": "cdefgh-ijklmn-345678901"
+        }
+
+Query Storage Capacity for a defined resource type
+""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Request to find out about available, reserved, total and allocated storage
+capacity.
+
+.. http:get:: /capacity/storage/query
+    :noindex:
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+        GET /capacity/storage/query HTTP/1.1
+        Accept: application/json
+
+        {
+            "storageResourceTypeId": "volumes",
+            "timePeriod":  {
+                "startTime": "2015-09-28T12:00:00Z",
+                "stopTime": "2015-09-28T12:04:45Z"
+            }
+        }
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+       HTTP/1.1 200 OK
+       Content-Type: application/json
+
+       {
+           "lastUpdate": "2015-09-28T12:01:35Z",
+           "capacityInformation": {
+               "available": 2,
+               "reserved": 4,
+               "total": 10,
+               "allocated": 4
+           }
+       }
+
+Query Storage Capacity with required attributes
+"""""""""""""""""""""""""""""""""""""""""""""""
+
+Request to find out available capacity.
+
+.. http:get:: /capacity/storage/query
+    :noindex:
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+        GET /capacity/storage/query HTTP/1.1
+        Accept: application/json
+
+        {
+            "resourceCriteria": {
+                "typeOfStorage" : "volume",
+                "sizeOfStorage" : 200,
+                "rdmaSupported" : "True",
+            },
+            "attributeSelector": "available",
+            "timePeriod":  {
+                "startTime": "2015-09-28T12:00:00Z",
+                "stopTime": "2015-09-28T12:04:45Z"
+            }
+        }
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+       HTTP/1.1 200 OK
+       Content-Type: application/json
+
+       {
+           "lastUpdate": "2015-09-28T12:01:35Z",
+           "capacityInformation": {
+               "available": 2
+           }
+       }
+
+Notify Storage Capacity Change Event
+""""""""""""""""""""""""""""""""""""
+
+Notification about storage capacity changes
+
+.. http:post:: /capacity/storage/notification
+    :noindex:
+
+    **Example notification**:
+
+    .. sourcecode:: http
+
+        Content-Type: application/json
+
+        {
+            "notificationId": "xwvuts-rqponm-765432109",
+            "capacityChangeTime": "2015-09-28T12:01:35Z",
+            "resourceDescriptor": {
+                "storageResourceTypeId": "volumes"
+            },
+            "capacityInformation": {
+                "available": 2,
+                "reserved": 4,
+                "total": 10,
+                "allocated": 4
+            }
+       }
+
+Storage Resource Reservation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create Storage Resource Reservation
+"""""""""""""""""""""""""""""""""""
+
+Request the reservation of storage resource capacity
+
+.. http:post:: /reservation/storage/create
+    :noindex:
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+        POST /reservation/storage/create HTTP/1.1
+        Accept: application/json
+
+        {
+            "startTime": "2015-09-28T13:00:00Z",
+            "storagePoolReservation": {
+                "storageSize": 10,
+                "numSnapshots": 3,
+                "numVolumes": 2
+            }
+        }
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+        HTTP/1.1 201 CREATED
+        Content-Type: application/json
+
+        {
+            "reservationData": {
+                "startTime": "2015-09-28T13:00:00Z",
+                "reservationStatus": "initialized",
+                "reservationId": "vvvv-wwww-xxxx",
+                "storagePoolReserved": {
+                    "storageSize": 10,
+                    "numSnapshots": 3,
+                    "numVolumes": 2
+                }
+            }
+        }
+
+Query Storage Resource Reservation
+""""""""""""""""""""""""""""""""""
+
+Request to find out about reserved storage resources that the consumer has
+access to.
+
+.. http:get:: /reservation/storage/query
+    :noindex:
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+        GET /reservation/storage/query HTTP/1.1
+        Accept: application/json
+
+        {
+            "queryReservationFilter": [
+                {
+                    "reservationId": "vvvv-wwww-xxxx"
+                }
+            ]
+        }
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Content-Type: application/json
+
+        {
+            "queryResult": {
+                "startTime": "2015-09-28T13:00:00Z",
+                "reservationStatus": "active",
+                "reservationId": "vvvv-wwww-xxxx",
+                "storagePoolReserved": {
+                    "storageSize": 10,
+                    "numSnapshots": 3,
+                    "numVolumes": 2
+                }
+            }
+        }
+
+Update Storage Resource Reservation
+"""""""""""""""""""""""""""""""""""
+
+Request to update storage resource reservation
+
+.. http:post:: /reservation/storage/update
+    :noindex:
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+        POST /reservation/storage/update HTTP/1.1
+        Accept: application/json
+
+
+        {
+            "startTime": "2015-09-20T23:00:00Z",
+            "reservationId": "vvvv-wwww-xxxx"
+
+        }
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+        HTTP/1.1 201 CREATED
+        Content-Type: application/json
+
+        {
+            "reservationData": {
+                "startTime": "2015-09-20T23:00:00Z",
+                "reservationStatus": "active",
+                "reservationId": "vvvv-wwww-xxxx",
+                "storagePoolReserved": {
+                    "storageSize": 10,
+                    "numSnapshots": 3,
+                    "numVolumes": 2
+                }
+            }
+        }
+
+Terminate Storage Resource Reservation
+""""""""""""""""""""""""""""""""""""""
+
+Request to terminate a storage resource reservation
+
+.. http:delete:: /reservation/storage/(reservation_id)
+   :noindex:
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+       HTTP/1.1 200
+       Content-Type: application/json
+
+       {
+          "reservationId": "xxxx-yyyy-zzzz",
+       }
diff --git a/docs/development/requirements/annex1.rst b/docs/development/requirements/annex1.rst
new file mode 100644
index 0000000..65a5f22
--- /dev/null
+++ b/docs/development/requirements/annex1.rst
@@ -0,0 +1,37 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _uc-brahmaputra:
+
+ANNEX A: Use case for OPNFV Brahmaputra
+=======================================
+
+A basic resource reservation use case to be realized for OPNFV B-release may
+look as follows:
+
+* Step 0: Shim-layer is monitoring/querying available capacity at NFVI
+
+  * Step 0a: Cloud operator creates a new OpenStack tenant user and updates
+    quota values for this user
+
+  * Step 0b: The tenant user is creating and instantiating a simple VNF
+    (e.g. 1 network, 2 VMs)
+
+  * Step 0c: OpenStack is notifying shim-layer about capacity change for
+    this new tenant user
+
+  * Step 0d: Cloud operator can visualize the changes using the GUI
+
+* Step 1: Consumer(NFVO) is sending a reservation request for future use to
+  shim-layer
+
+* Step 2: Shim-layer is checking for available capacity at the given time
+  window
+
+* Step 3: Shim-layer is responding with reservation identifier
+
+* Step 4 (optional): Consumer(NFVO) is sending an update reservation request
+  to shim-layer (startTime set to now) -> continue with Steps 2 and 3.
+
+* Step 5: Consumer(VNFM) is requesting the allocation of virtualised resources
+  using the reservation identifier in Step 3
diff --git a/docs/development/requirements/architecture.rst b/docs/development/requirements/architecture.rst
new file mode 100644
index 0000000..3eb20d3
--- /dev/null
+++ b/docs/development/requirements/architecture.rst
@@ -0,0 +1,258 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+============================================
+High level architecture and general features
+============================================
+
+Architecture Overview
+=====================
+
+.. figure:: images/figure1.png
+   :name: figure1
+   :width: 90%
+
+   Resource Reservation Architecture
+
+:numref:`figure1` shows the high level architecture for the resource reservation
+use cases. Reserved resources are guaranteed for a given user/client for the
+period expressed by start and end time. User/client represents the requestor
+and the consequent consumer of the reserved resources and correspond to the
+NFVO or VNFM in ETSI NFV terminology.
+
+Note: in this document only reservation requests from NFVO are considered.
+
+General Features
+================
+
+This section provides a list of features that need to be developed in the
+Promise project.
+
+* Resource capacity management
+
+  * Discovery of available resource capacity in resource providers
+  * Monitoring of available resource capacity in resource providers
+  * Update available resource capacity as a result of new or expired
+    reservations, addition/removal of resources. Note: this is a VIM internal
+    function, not an operation in the VIM northbound interface.
+
+* Resource reservation
+
+  * Set start time and end time for allocation
+  * Increase/decrease reserved resource's capacity
+  * Update resource reservations, e.g. add/remove reserved resources
+  * Terminate an allocated resource due to the end time of a reservation
+
+* VIM northbound interfaces
+
+  * Receive/Reply resource reservation requests
+  * Receive/Reply resource capacity management requests
+  * Receive/Reply resource allocation requests for reserved resources when
+    start time arrives
+  * Subscribe/Notify resource reservation event
+
+    * Notify reservation error or process completion prior to reservation
+      start
+    * Notify remaining time until termination of a resource due to the end
+      time of a reservation
+    * Notify termination of a resource due to the end time of a reservation
+
+  * Receive/Reply queries on available resource capacity
+  * Subscribe/Notify changes in available resource capacity
+
+High level northbound interface specification
+=============================================
+
+Resource Capacity Management
+----------------------------
+
+.. figure:: images/figure2.png
+   :name: figure2
+   :width: 90%
+
+   Resource capacity management message flow: notification of capacity change
+
+:numref:`figure2` shows a high level flow for a use case of resource capacity
+management. In this example, the VIM notifies the NFVO of capacity change after
+having received an event regarding a change in capacity (e.g. a fault
+notification) from the NFVI. The NFVO can also retrieve detailed capacity
+information using the Query Capacity Request interface operation.
+
+.. figure:: images/figure3.png
+   :name: figure3
+   :width: 90%
+
+   Resource capacity management message flow: query of capacity density
+
+:numref:`figure3` shows a high level flow for another use case of resource
+capacity management. In this example, the NFVO queries the VIM about the actual
+capacity to instantiate a certain resource according to a certain template, for
+example a VM according to a certain flavor. In this case the VIM responds with
+the number of VMs that could be instantiated according to that flavor with the
+currently available capacity.
+
+Resource Reservation
+--------------------
+
+.. figure:: images/figure4.png
+   :name: figure4
+   :width: 90%
+
+   Resource reservation flow
+
+:numref:`figure4` shows a high level flow for a use case of resource
+reservation. The main steps are:
+
+* The NFVO sends a resource reservation request to the VIM using the Create
+  Resource Reservation Request interface operation.
+* The NFVO gets a reservation identifier reservation associated with this
+  request in the reply message
+* Using the reservation identifier reservation, the NFVO can
+  query/update/terminate a resource reservation using the corresponding
+  interface operations
+* The NFVO is notified that the resource reservation is terminated due to the
+  end time of the reservation
+
+
+Information elements
+====================
+
+Resource Capacity Management
+----------------------------
+
+Notify Capacity Change Event
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The notification change message shall include the following information elements:
+
+============================ ========== =====================================
+Name                         Type       Description
+============================ ========== =====================================
+Notification                 Identifier Identifier issued by the VIM for the
+                                        capacity change event notification
+Zone                         Identifier Identifier of the zone where capacity
+                                        has changed
+Used/Reserved/Total Capacity List       Used, reserved and total capacity
+                                        information regarding the resource
+                                        items subscribed for notification for
+                                        which capacity change event occurred
+============================ ========== =====================================
+
+Query Resource Capacity Request
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The capacity management query request message shall include the following
+information elements:
+
+========== ========== ======================================================
+Name       Type       Description
+========== ========== ======================================================
+Zone       Identifier Identifier of the zone where capacity is requested
+Attributes List       Attributes of resource items to be notified regarding
+                      capacity change events
+Resources  List       Identifiers of existing resource items to be queried
+                      regarding capacity info (such as images, flavors,
+                      virtual containers, networks, physical machines, etc.)
+========== ========== ======================================================
+
+The capacity management query request message may also include the following
+information element:
+
+====== ========== ==========================================================
+Name   Type       Description
+====== ========== ==========================================================
+Flavor Identifier Identifier that is passed in the request to obtain
+                  information of the number of virtual resources that can be
+                  instantiated according to this flavor with the available
+                  capacity
+====== ========== ==========================================================
+
+Query Resource Capacity Reply
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The capacity management query reply message shall include the following
+information elements:
+
+============================ ========== =====================================
+Name                         Type       Description
+============================ ========== =====================================
+Zone                         Identifier Identifier of the zone where capacity
+                                        is requested
+Used/Reserved/Total Capacity List       Used, reserved and total capacity
+                                        information regarding each of the
+                                        resource items requested to check for
+                                        capacity
+============================ ========== =====================================
+
+The detailed specification of the northbound interface for Capacity Management
+in provided in section 5.1.1.
+
+Resource Reservation
+--------------------
+
+Create Resource Reservation Request
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The create resource reservation request message shall include the following
+information elements:
+
+========== ========== =========================================================
+Name       Type       Description
+========== ========== =========================================================
+Start      Timestamp  Start time for consumption of the reserved resources
+End        Timestamp  End time for consumption of the reserved resources
+Expiry     Timestamp  If not all reserved resources are allocated between start
+                      time and expiry, the VIM shall release the corresponding
+                      resources [#expiry]_
+Amount     Number     Amount of the resources per resource item type (i.e.
+                      compute/network/storage) that need to be reserved
+Zone       Identifier The zone  where the resources need(s) to be reserved
+Attributes List       Attributes of the resources to be reserved such as DPDK
+                      support, hypervisor, network link bandwidth, affinity
+                      rules, etc.
+Resources  List       Identifiers of existing resource items to be reserved
+                      (such as images, flavors, virtual containers, networks,
+                      physical machines, etc.)
+========== ========== =========================================================
+
+.. [#expiry] Expiry is a period around start time within which, the allocation
+             process must take place. If allocation process does not start
+             within the expiry period, the reservation becomes invalid and VIM
+             should release the resources
+
+Create Resource Reservation Reply
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The create resource reservation reply message shall include the following
+information elements:
+
+=========== ========== =======================================================
+Name        Type       Description
+=========== ========== =======================================================
+Reservation Identifier Identification of the reservation instance. It can be
+                       used by a consumer to modify the reservation later, and
+                       to request the allocation of the reserved resources.
+Message     Text       Output message that provides additional information
+                       about the create resource reservation request (e.g. may
+                       be a simple ACK if the request is being background
+                       processed by the VIM)
+=========== ========== =======================================================
+
+Notify Reservation Event
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The notification reservation event message shall include the following
+information elements:
+
+============ ========== =====================================================
+Name         Type       Description
+============ ========== =====================================================
+Reservation  Identifier Identification of the reservation instance triggering
+                        the event
+Notification Identifier Identification of the resource event notification
+                        issued by the VIM
+Message      Text       Message describing the event
+============ ========== =====================================================
+
+The detailed specification of the northbound interface for Resource Reservation
+is provided in section 5.1.2.
diff --git a/docs/development/requirements/gap_analysis.rst b/docs/development/requirements/gap_analysis.rst
new file mode 100644
index 0000000..9e4ec5c
--- /dev/null
+++ b/docs/development/requirements/gap_analysis.rst
@@ -0,0 +1,99 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+=================================
+Gap analysis in upstream projects
+=================================
+
+This section provides a list of gaps in upstream projects for realizing
+resource reservation and management. The gap analysis work focuses on the
+current OpenStack Blazar project [BLAZAR]_ in this first release.
+
+OpenStack
+=========
+
+Resource reservation for future use
+-----------------------------------
+
+* Category: Blazar
+* Type: 'missing' (lack of functionality)
+* Description:
+
+  * To-be: To reserve a whole set of compute/storage/network resources in the
+    future
+  * As-is: Blazar currently can do only compute resource reservation by using
+    "Shelved VM"
+
+* Related blueprints:
+
+  * https://blueprints.launchpad.net/blazar/+spec/basic-volume-plugin
+  * https://blueprints.launchpad.net/blazar/+spec/basic-network-plugin
+  * It was planned in Blazar to implement volume and network/fixed ip
+    reservations
+
+Resource reservation update
+---------------------------
+
+* Category: Blazar
+* Type: 'missing' (lack of functionality)
+* Description:
+
+  * To-be: Have the possibility of adding/removing resources to an existing
+    reservation, e..g in case of NFVI failure
+  * As-is: Currently in Blazar, a reservation can only be modified in terms of
+    start/end time
+
+* Related blueprints: N/A
+
+Give me an offer
+----------------
+
+* Category: Blazar
+* Type: 'missing' (lack of functionality)
+* Description:
+
+  * To-be: To have the possibility of giving a quotation to a requesting user
+    and an expiration time. Reserved resources shall be released if they are
+    not claimed before this expiration time.
+  * As-is: Blazar can already send notification e.g. to inform a given user
+    that a reservation is about to expire
+
+* Related blueprints: N/A
+
+StormStack StormForge
+---------------------
+
+Stormify
+^^^^^^^^
+* Stormify enables rapid web applications construction
+* Based on Ember.js style Data stores
+* Developed on Node.js using coffeescript/javascript
+* Auto RESTful API generation based on Data Models
+* Development starts with defining Data Models
+* Code hosted at github : http://github.com/stormstack/stormify
+
+StormForge
+^^^^^^^^^^
+* Data Model driven management of Resource Providers
+* Based on Stormify Framework and implemented as per the OPNFV Promise
+  requirements
+* Data Models are auto generated and RESTful API code from YANG schema
+* Currently planned key services include Resource Capacity Management Service
+  and Resource Reservation Service
+* List of YANG schemas for Promise project is attached in the Appendix
+* Code hosted at github: http://github.com/stormstack/stormforge
+
+Resource Discovery
+^^^^^^^^^^^^^^^^^^
+* Category: StormForge
+* Type: 'planning' (lack of functionality)
+* Description
+
+  * To-be: To be able to discover resources in real time from OpenStack
+    components. Planning to add OpenStack Project to interface with Promise for
+    real time updates on capacity or any failures
+  * As-is: Currently, resource capacity is learnt using NB APIs related to
+    quota
+
+* Related Blueprints: N/A
+
diff --git a/docs/development/requirements/glossary.rst b/docs/development/requirements/glossary.rst
new file mode 100644
index 0000000..48fd75b
--- /dev/null
+++ b/docs/development/requirements/glossary.rst
@@ -0,0 +1,73 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+===================
+Definition of terms
+===================
+
+Different SDOs and communities use different terminology related to
+NFV/Cloud/SDN. This list tries to define an OPNFV terminology,
+mapping/translating the OPNFV terms to terminology used in other contexts.
+
+.. glossary::
+
+   Administrator
+      Administrator of the system, e.g. OAM in Telco context.
+
+   Consumer
+      User-side Manager; consumer of the interfaces produced by the VIM; VNFM,
+      NFVO, or Orchestrator in ETSI NFV [NFV003]_ terminology.
+
+   NFV
+      Network Function Virtualization
+
+   NFVI
+      Network Function Virtualization Infrastructure; totality of all hardware
+      and software components which build up the environment in which VNFs are
+      deployed.
+
+   NFVO
+      Network Functions Virtualization Orchestrator; functional block that
+      manages the Network Service (NS) lifecycle and coordinates the management
+      of NS lifecycle, VNF lifecycle (supported by the VNFM) and NFVI resources
+      (supported by the VIM) to ensure an optimized allocation of the necessary
+      resources and connectivity.
+
+   Physical resource
+      Actual resources in NFVI; not visible to Consumer.
+
+   Resource zone
+      A set of NFVI hardware and software resources logically grouped
+      according to physical isolation and redundancy capabilities or to
+      certain administrative policies for the NFVI [NFVIFA010]_
+
+   VIM
+      Virtualized Infrastructure Manager; functional block that is responsible
+      for controlling and managing the NFVI compute, storage and network
+      resources, usually within one operator's Infrastructure Domain, e.g. NFVI
+      Point of Presence (NFVI-PoP).
+
+   Virtual Machine (VM)
+      Virtualized computation environment that behaves very much like a physical
+      computer/server.
+
+   Virtual network
+      Virtual network routes information among the network interfaces of VM
+      instances and physical network interfaces, providing the necessary
+      connectivity.
+
+   Virtual resource
+      A Virtual Machine (VM), a virtual network, or virtualized storage; Offered
+      resources to "Consumer" as result of infrastructure virtualization;
+      visible to Consumer.
+
+   Virtual Storage
+      Virtualized non-volatile storage allocated to a VM.
+
+   VNF
+      Virtualized Network Function. Implementation of an Network Function that
+      can be deployed on a Network Function Virtualization Infrastructure (NFVI).
+
+   VNFM
+      Virtualized Network Function Manager; functional block that is responsible
+      for the lifecycle management of VNF.
diff --git a/docs/development/requirements/images/LICENSE b/docs/development/requirements/images/LICENSE
new file mode 100644
index 0000000..3b8719c
--- /dev/null
+++ b/docs/development/requirements/images/LICENSE
@@ -0,0 +1,14 @@
+Copyright 2015 Open Platform for NFV Project, Inc. and its contributors
+
+Open Platform for NFV Project Documentation Licence
+===================================================
+Any documentation developed by the "Open Platform for NFV Project"
+is licensed under a Creative Commons Attribution 4.0 International License.
+You should have received a copy of the license along with this. If not,
+see <http://creativecommons.org/licenses/by/4.0/>.
+
+Unless required by applicable law or agreed to in writing, documentation
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
diff --git a/docs/development/requirements/images/computeflavor.png b/docs/development/requirements/images/computeflavor.png
new file mode 100755
index 0000000..3ea3dba
--- /dev/null
+++ b/docs/development/requirements/images/computeflavor.png
diff --git a/docs/development/requirements/images/figure1.png b/docs/development/requirements/images/figure1.png
new file mode 100644
index 0000000..065a995
--- /dev/null
+++ b/docs/development/requirements/images/figure1.png
diff --git a/docs/development/requirements/images/figure2.png b/docs/development/requirements/images/figure2.png
new file mode 100755
index 0000000..dd002a2
--- /dev/null
+++ b/docs/development/requirements/images/figure2.png
diff --git a/docs/development/requirements/images/figure3.png b/docs/development/requirements/images/figure3.png
new file mode 100755
index 0000000..20e51c7
--- /dev/null
+++ b/docs/development/requirements/images/figure3.png
diff --git a/docs/development/requirements/images/figure4.png b/docs/development/requirements/images/figure4.png
new file mode 100755
index 0000000..e0c96a1
--- /dev/null
+++ b/docs/development/requirements/images/figure4.png
diff --git a/docs/development/requirements/images/figure5.png b/docs/development/requirements/images/figure5.png
new file mode 100755
index 0000000..4e161f4
--- /dev/null
+++ b/docs/development/requirements/images/figure5.png
diff --git a/docs/development/requirements/images/figure5_new.png b/docs/development/requirements/images/figure5_new.png
new file mode 100644
index 0000000..9307aa2
--- /dev/null
+++ b/docs/development/requirements/images/figure5_new.png
diff --git a/docs/development/requirements/images/figure6.png b/docs/development/requirements/images/figure6.png
new file mode 100755
index 0000000..8aeec23
--- /dev/null
+++ b/docs/development/requirements/images/figure6.png
diff --git a/docs/development/requirements/images/figure6_new.png b/docs/development/requirements/images/figure6_new.png
new file mode 100644
index 0000000..5ec4b43
--- /dev/null
+++ b/docs/development/requirements/images/figure6_new.png
diff --git a/docs/development/requirements/images/figure7_new.png b/docs/development/requirements/images/figure7_new.png
new file mode 100644
index 0000000..6684949
--- /dev/null
+++ b/docs/development/requirements/images/figure7_new.png
diff --git a/docs/development/requirements/impl_architecture.rst b/docs/development/requirements/impl_architecture.rst
new file mode 100644
index 0000000..d7375d5
--- /dev/null
+++ b/docs/development/requirements/impl_architecture.rst
@@ -0,0 +1,313 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Detailed architecture and message flows
+=======================================
+
+Within the Promise project we consider two different architectural options, i.e.
+a *shim-layer* based architecture and an architecture targeting at full
+OpenStack *integration*.
+
+Shim-layer architecture
+-----------------------
+
+The *shim-layer architecture* is using a layer on top of OpenStack to provide
+the capacity management, resource reservation, and resource allocation features.
+
+
+Detailed Message Flows
+^^^^^^^^^^^^^^^^^^^^^^
+
+Note, that only selected parameters for the messages are shown. Refer to
+:ref:`northbound_API` and Annex :ref:`yang_schema` for a full set of message
+parameters.
+
+Resource Capacity Management
+""""""""""""""""""""""""""""
+
+.. figure:: images/figure5_new.png
+    :name: figure5
+    :width: 90%
+
+    Capacity Management Scenario
+
+:numref:`figure5` shows a detailed message flow between the consumers and the
+capacity management functional blocks inside the shim-layer. It has the
+following steps:
+
+    * Step 1a: The Consumer sends a *query-capacity* request to Promise
+      using some filter like time-windows or resource type. The capacity is
+      looked up in the shim-layer capacity map.
+
+    * Step 1b: The shim-layer will respond with information about the
+      total, available, reserved, and used (allocated) capacities matching the
+      filter.
+
+    * Step 2a: The Consumer can send *increase/decrease-capacity* requests
+      to update the capacity available to the reservation system. It can be
+      100% of available capacity in the given provider/source or only a subset,
+      i.e., it can allow for leaving some "buffer" in the actual NFVI to be
+      used outside the Promise shim-layer or for a different reservation
+      service instance. It can also be used to inform the reservation system
+      that from a certain time in the future, additional resources can be
+      reserved (e.g. due to a planned upgrade of the capacity), or the
+      available capacity will be reduced (e.g. due to a planned downtime of
+      some of the resources).
+
+    * Step 2b: The shim-layer will respond with an ACK/NACK message.
+
+    * Step 3a: Consumers can subscribe for capacity-change events using a
+      filter.
+
+    * Step 3b: Each successful subscription is responded with a
+      subscription_id.
+
+    * Step 4: The shim-layer monitors the capacity information for the
+      various types of resources by periodically querying the various
+      Controllers (e.g. Nova, Neutron, Cinder) or by creating event alarms in
+      the VIM (e.g. with Ceilometer for OpenStack) and updates capacity
+      information in its capacity map.
+
+    * Step 5: Capacity changes are notified to the Consumer.
+
+Resource Reservation
+""""""""""""""""""""
+
+.. figure:: images/figure6_new.png
+    :name: figure6
+    :width: 90%
+
+    Resource Reservation for Future Use Scenario
+
+:numref:`figure6` shows a detailed message flow between the Consumer and the
+resource reservation functional blocks inside the shim-layer. It has the
+following steps:
+
+    * Step 1a: The Consumer creates a resource reservation request for
+      future use by setting a start and end time for the reservation as well as
+      more detailed information about the resources to be reserved. The Promise
+      shim-layer will check the free capacity in the given time window and in
+      case sufficient capacity exists to meet the reservation request, will
+      mark those resources "reserved" in its reservation map.
+
+    * Step 1b: If the reservation was successful, a reservation_id and
+      status of the reservation will be returned to the Consumer. In case the
+      reservation cannot be met, the shim-layer may return information about
+      the maximum capacity that could be reserved during the requested time
+      window and/or a potential time window where the requested (amount of)
+      resources would be available.
+
+    * Step 2a: Reservations can be updated using an *update-reservation*,
+      providing the reservation_id and the new reservation_data. Promise
+      Reservation Manageer will check the feasibility to update the reservation
+      as requested.
+
+    * Step 2b: If the reservation was updated successfully, a
+      reservation_id and status of the reservation will be returned to the
+      Consumer. Otherwise, an appropriate error message will be returned.
+
+    * Step 3a: A *cancel-reservation* request can be used to withdraw an
+      existing reservation. Promise will update the reservation map by removing
+      the reservation as well as the capacity map by adding the freed capacity.
+
+    * Step 3b: The response message confirms the cancelation.
+
+    * Step 4a: Consumers can also issue *query-reservation* requests to
+      receive a list of reservation. An input filter can be used to narrow down
+      the query, e.g., only provide reservations in a given time window.
+      Promise will query its reservation map to identify reservations matching
+      the input filter.
+
+    * Step 4b: The response message contains information about all
+      reservations matching the input filter. It also provides information
+      about the utilization in the requested time window.
+
+    * Step 5a: Consumers can subscribe for reservation-change events using
+      a filter.
+
+    * Step 5b: Each successful subscription is responded with a
+      subscription_id.
+
+    * Step 6a: Promise synchronizes the available and used capacity with
+      the underlying VIM.
+
+    * Step 6b: In certain cases, e.g., due a failure in the underlying
+      hardware, some reservations cannot be kept up anymore and have to be
+      updated or canceled. The shim-layer will identify affected reservations
+      among its reservation records.
+
+    * Step 7: Subscribed Consumers will be informed about the updated
+      reservations. The notification contains the updated reservation_data and
+      new status of the reservation. It is then up to the Consumer to take
+      appropriate actions in order to ensure high priority reservations are
+      favored over lower priority reservations.
+
+Resource Allocation
+"""""""""""""""""""
+
+.. figure:: images/figure7_new.png
+    :name: figure7
+    :width: 90%
+
+    Resource Allocation
+
+:numref:`figure7` shows a detailed message flow between the Consumer, the
+functional blocks inside the shim-layer, and the VIM. It has the following
+steps:
+
+    * Step 1a: The Consumer sends a *create-instance* request providing
+      information about the resources to be reserved, i.e., provider_id
+      (optional in case of only one provider), name of the instance, the
+      requested flavour and image, etc. If the allocation is against an
+      existing reservation, the reservation_id has to be provided.
+
+    * Step 1b: If a reservation_id was provided, Promise checks if a
+      reservation with that ID exists, the reservation start time has arrived
+      (i.e. the reservation is active), and the required capacity for the
+      requested flavor is within the available capacity of the reservation. If
+      those conditions are met, Promise creates a record for the allocation
+      (VMState="INITIALIZED") and update its databases. If no reservation_id
+      was provided in the allocation request, Promise checks whether the
+      required capacity to meet the request can be provided from the available,
+      non-reserved capacity. If yes, Promise creates a record for the
+      allocation and update its databases. In any other case, Promise rejects
+      the *create-instance* request.
+
+    * Step 2: In the case the *create-instance* request was rejected,
+      Promise responds with a "status=rejected" providing the reason of the
+      rejection. This will help the Consumer to take appropriate actions, e.g.,
+      send an updated *create-instance* request. The allocation work flow will
+      terminate at this step and the below steps are not executed.
+
+    * Step 3a: If the *create-instance* request was accepted and a related
+      allocation record has been created, the shim-layer issues a
+      *createServer* request to the VIM Controller providing all information to
+      create the server instance.
+
+    * Step 3b: The VIM Controller sends an immediate reply with an
+      instance_id and starts the VIM-internal allocation process.
+
+    * Step 4: The Consumer gets an immediate response message with
+      allocation status "in progress" and the assigned instance_id.
+
+    * Step 5a+b: The consumer subscribes to receive notifications about
+      allocation events related to the requested instance. Promise responds
+      with an acknowledgment including a subscribe_id.
+
+    * Step 6: In parallel to the previous step, Promise shim-layer creates
+      an alarm in Aodh to receive notifications about all changes to the
+      VMState for instance_id.
+
+    * Step 7a: The VIM Controller notifies all instance related events to
+      Ceilometer. After the allocation has been completed or failed, it sends
+      an event to Ceilometer. This triggers the OpenStack alarming service Aodh
+      to notify the new VMState (e.g. ACTIVE and ERROR) to the shim-layer that
+      updates its internal allocation records.
+
+    * Step 7b: Promise sends a notification message to the subscribed
+      Consumer with information on the allocated resources including their new
+      VMState.
+
+    * Step 8a+b: Allocated instances can be terminated by the Consumer by
+      sending a *destroy-instance* request to the shim-layer. Promise responds
+      with an acknowledgment and the new status "DELETING" for the instance.
+
+    * Step 9a: Promise sends a *deleteServer* request for the instance_id
+      to the VIM Controller.
+
+    * Step 10a: After the instance has been deleted, an event alarm is
+      sent to the shim-layer that updates its internal allocation records and
+      capacity utilization.
+
+    * Step 10b: The shim-layer also notifies the subscribed Consumer about
+      the successfully destroyed instance.
+
+
+Internal operations
+^^^^^^^^^^^^^^^^^^^
+
+.. note:: This section is to be updated
+
+In the following, the internal logic and operations of the shim-layer will be
+explained in more detail, e.g. the "check request" (step 1b in
+:numref:`figure7` of the allocation work flow).
+
+
+
+Integrated architecture
+-----------------------
+
+The *integrated architecture* aims at full integration with OpenStack.
+This means that it is planned to use the already existing OpenStack APIs
+extended with the reservation capabilities.
+
+The advantage of this approach is that we don't need to re-model the
+complex resource structure we have for the virtual machines and the
+corresponding infrastructure.
+
+The atomic item is the virtual machine with the minimum set of resources
+it requires to be able to start it up. It is important to state that
+resource reservation is handled on VM instance level as opposed to standalone
+resources like CPU, memory and so forth. As the placement is an important
+aspect in order to be able to use the reserved resources it provides the
+constraint to handle resources in groups.
+
+The placement constraint also makes it impossible to use a quota management
+system to solve the base use case described earlier in this document.
+
+OpenStack had a project called Blazar, which was created in order to provide
+resource reservation functionality in cloud environments. It uses the Shelve
+API of Nova, which provides a sub-optimal solution. Due to the fact that this
+feature blocks the reserved resources this solution cannot be considered to
+be final. Further work is needed to reach a more optimal stage, where the
+Nova scheduler is intended to be used to schedule the resources for future
+use to make the reservations.
+
+Phases of the work
+^^^^^^^^^^^^^^^^^^
+
+The work has two main stages to reach the final solution. The following main work items
+are on the roadmap for this approach:
+
+#. Sub-optimal solution by using the shelve API of Nova through the Blazar project:
+
+   * Fix the code base of the Blazar project:
+
+     Due to integration difficulties the Blazar project got suspended. Since the last
+     activities in that repository the OpenStack code base and environment changed
+     significantly, which means that the project's code base needs to be updated to the
+     latest standards and has to be able to interact with the latest version of the
+     other OpenStack services.
+
+   * Update the Blazar API:
+
+     The REST API needs to be extended to contain the attributes for the reservation
+     defined in this document. This activity shall include testing towards the new API.
+
+#. Use Nova scheduler to avoid blocking the reserved resources:
+
+   * Analyze the Nova scheduler:
+
+     The status and the possible interface between the resource reservation system and
+     the Nova scheduler needs to be identified. It is crucial to achieve a much more
+     optimal solution than what the current version of Blazar can provide. The goal is
+     to be able to use the reserved resources before the reservation starts. In order to
+     be able to achieve this we need the scheduler to do scheduling for the future
+     considering the reservation intervals that are specified in the request.
+
+   * Define a new design based on the analysis and start the work on it:
+
+     The design for the more optimal solution can be defined only after analyzing the
+     structure and capabilities of the Nova scheduler.
+
+   * This phase can be started in parallel with the previous one.
+
+Detailed Message Flows
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. note:: to be done
+
+Resource Reservation
+""""""""""""""""""""
+
+.. note:: to be specified
diff --git a/docs/development/requirements/index.rst b/docs/development/requirements/index.rst
new file mode 100644
index 0000000..00edf0e
--- /dev/null
+++ b/docs/development/requirements/index.rst
@@ -0,0 +1,52 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+****************************
+Promise: Resource Management
+****************************
+
+:Project: Promise, https://wiki.opnfv.org/promise
+:Editors: Ashiq Khan (NTT DOCOMO), Bertrand Souville (NTT DOCOMO)
+:Authors: Ravi Chunduru (ClearPath Networks), Peter Lee (ClearPath Networks),
+          Gerald Kunzmann (NTT DOCOMO), Ryota Mibu (NEC),
+          Carlos Goncalves (NEC), Arturo Martin De Nicolas (Ericsson)
+
+:History:
+          ========== =====================================================
+          Date       Description
+          ========== =====================================================
+          04.12.2014 Project creation
+          20.04.2015 Initial version of the deliverable uploaded to gerrit
+          19.06.2015 Stable version of the Promise deliverable
+          ========== =====================================================
+
+:Abstract: Promise is an OPNFV requirement project. Its objective is to realize
+           ETSI NFV defined resource reservation and NFVI capacity features
+           within the scope of OPNFV. Promise provides the details of the
+           requirements on resource reservation, NFVI capacity management at
+           VIM, specification of the northbound interfaces from VIM relevant to
+           these features, and implementation plan to realize these features in
+           OPNFV.
+
+.. raw:: latex
+
+    \newpage
+
+.. toctree::
+   :maxdepth: 4
+   :numbered:
+
+   glossary.rst
+   intro.rst
+   usecase.rst
+   architecture.rst
+   gap_analysis.rst
+   impl_architecture.rst
+   NB_interface.rst
+   summary.rst
+
+   references.rst
+   annex1.rst
+   schemas.rst
+   supported_apis.rst
+   revision.rst
diff --git a/docs/development/requirements/intro.rst b/docs/development/requirements/intro.rst
new file mode 100644
index 0000000..654fdf9
--- /dev/null
+++ b/docs/development/requirements/intro.rst
@@ -0,0 +1,39 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+============
+Introduction
+============
+
+Resource reservation is a basic function for the operation of a virtualized
+telecom network. In resource reservation, VIM reserves resources for a certain
+period as requested by the NFVO. A resource reservation will have a start time
+which could be into the future. Therefore, the reserved resources shall be
+available for the NFVO requested purpose (e.g. for a VNF) at the start time for
+the duration asked by NFVO. Resources include all three resource types in an
+NFVI i.e. compute, storage and network.
+
+Besides, NFVO requires abstracted NFVI resource capacity information in order
+to take decisions on VNF placement and other operations related to the virtual
+resources. VIM is required to inform the NFVO of NFVI resource state
+information for this purpose. Promise project aims at delivering the detailed
+requirements on these two features defined in ETSI NFV MAN GS [NFVMAN]_,
+the list of gaps in upstream projects, potential implementation architecture
+and plan, and the VIM northbound interface specification for resource
+reservation and capacity management.
+
+Problem description
+===================
+
+OpenStack, a prominent candidate for the VIM, cannot reserve resources for
+future use. OpenStack requires immediate instantiation of Virtual Machines
+(VMs) in order to occupy resources intended to be reserved. Blazar can reserve
+compute resources for future by keeping the VMs in shelved mode. However, such
+reserved resources can also be used for scaling out rather than new VM
+instantiation. Blazar does not support network and storage resource reservation
+yet.
+
+Besides, OpenStack does not provide a northbound interface through which it can
+notify an upper layer management entity e.g. NFVO about capacity changes in its
+NFVI, periodically or in an event driven way. Capacity management is a feature
+defined in ETSI NFV MAN GS [NFVMAN]_ and is required in network operation.
diff --git a/docs/development/requirements/references.rst b/docs/development/requirements/references.rst
new file mode 100644
index 0000000..c498b66
--- /dev/null
+++ b/docs/development/requirements/references.rst
@@ -0,0 +1,25 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+References and bibliography
+===========================
+
+.. [PROMISE]   OPNFV, "Promise" requirements project, [Online]. Available at
+               https://wiki.opnfv.org/promise
+.. [BLAZAR]    OpenStack Blazar Project, [Online]. Available at
+               https://wiki.openstack.org/wiki/Blazar
+.. [PROMOSS]   Promise reference implementation, [Online]. Available at
+               https://github.com/opnfv/promise
+.. [YANGFO]    Yangforge Project, [Online]. Available at
+               https://github.com/opnfv/yangforge
+.. [NFVMAN]    ETSI GS NFV MAN 001, "Network Function Virtualisation (NFV); Management and Orchestration"
+.. [NFV003]    ETSI GS NFV 003, "Network Function Virtualisation (NFV); Terminology for Main Concepts in NFV"
+.. [NFVIFA010] ETSI GS NFV IFA 010, "Network Function Virtualisation (NFV); Management and Orchestration;
+               Functional Requirements Specification"
+.. [NFVIFA005] ETSI GS NFV IFA 005, "Network Function Virtualisation (NFV); Management and Orchestration;
+               Or-Vi reference point - Interface and Information Model Specification"
+.. [NFVIFA006] ETSI GS NFV IFA 006 "Network Function Virtualisation (NFV); Management and Orchestration;
+               Vi-Vnfm reference point - Interface and Information Model Specification"
+.. [ETSINFV]   ETSI NFV, [Online]. Available at
+               http://www.etsi.org/technologies-clusters/technologies/nfv
+
diff --git a/docs/development/requirements/revision.rst b/docs/development/requirements/revision.rst
new file mode 100644
index 0000000..cd0b76b
--- /dev/null
+++ b/docs/development/requirements/revision.rst
@@ -0,0 +1,43 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+ANNEX D: Document revision
+==========================
+
++---------+-----------------------------------------+
+| Version |      Description                        |
++---------+-----------------------------------------+
+| 1.0.1   | JIRA: PROMISE-23                        |
+|         |  - Reference to YangForge Framework     |
+|         |  - Corrections to figure 3.1            |
++---------+-----------------------------------------+
+| 1.0.2   | JIRA: PROMISE-11                        |
+|         |  - OPNFV Logo Added                     |
+|         |  - Alignment to ETSI NFV Specs          |
++---------+-----------------------------------------+
+| 1.0.3   | JIRA: PROMISE-54                        |
+|         |  - Use case for Brahmaputra             |
++---------+-----------------------------------------+
+| 1.0.4   | JIRA: PROMISE-60                        |
+|         |  - Editorial fixes                      |
+|         |                                         |
+|         | JIRA: PROMISE-57                        |
+|         |  - Split shim-layer architecture and    |
+|         |    integrated architecture sections     |
++---------+-----------------------------------------+
+| 1.0.5   | JIRA: PROMISE-61                        |
+|         |  - Updated Promise Yang Schema          |
++---------+-----------------------------------------+
+| 1.0.6   | JIRA: PROMISE-62                        |
+|         |  - Supported APIs for Brahmaputra       |
++---------+-----------------------------------------+
+| 1.0.7   | JIRA: PROMISE-63                        |
+|         |  - Update message flow for shim-layer   |
+|         | JIRA: PROMISE-58                        |
+|         |  - Integrated approach description      |
+|         | JIRA: PROMISE-64                        |
+|         |  - Promise userguide                    |
++---------+-----------------------------------------+
+| 1.0.8   | JIRA: PROMISE-11                        |
+|         |  - Alignment to ETSI NVF Specs          |
++---------+-----------------------------------------+
diff --git a/docs/development/requirements/schemas.rst b/docs/development/requirements/schemas.rst
new file mode 100644
index 0000000..c98b7da
--- /dev/null
+++ b/docs/development/requirements/schemas.rst
@@ -0,0 +1,658 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _yang_schema:
+
+ANNEX B: Promise YANG schema based on YangForge
+===============================================
+
+.. code::
+
+  module opnfv-promise {
+  namespace "urn:opnfv:promise";
+  prefix promise;
+
+  import complex-types { prefix ct; }
+  import ietf-yang-types { prefix yang; }
+  import ietf-inet-types { prefix inet; }
+  import access-control-models { prefix acm; }
+  import nfv-infrastructure { prefix nfvi; }
+  import nfv-mano { prefix mano; }
+
+  description
+    "OPNFV Promise Resource Reservation/Allocation controller module";
+
+  revision 2015-10-05 {
+    description "Complete coverage of reservation related intents";
+  }
+
+  revision 2015-08-06 {
+    description "Updated to incorporate YangForge framework";
+  }
+
+  revision 2015-04-16 {
+    description "Initial revision.";
+  }
+
+  feature reservation-service {
+    description "When enabled, provides resource reservation service";
+  }
+
+  feature multi-provider {
+    description "When enabled, provides resource management across multiple providers";
+  }
+
+  typedef reference-identifier {
+    description "defines valid formats for external reference id";
+    type union {
+      type yang:uuid;
+      type inet:uri;
+      type uint32;
+    }
+  }
+
+  grouping resource-utilization {
+    container capacity {
+      container total     { description 'Conceptual container that should be extended'; }
+      container reserved  { description 'Conceptual container that should be extended';
+                            config false; }
+      container usage     { description 'Conceptual container that should be extended';
+                            config false; }
+      container available { description 'Conceptual container that should be extended';
+                            config false; }
+    }
+  }
+
+  grouping temporal-resource-collection {
+    description
+      "Information model capturing resource-collection with start/end time window";
+
+    leaf start { type yang:date-and-time; }
+    leaf end   { type yang:date-and-time; }
+
+    uses nfvi:resource-collection;
+  }
+
+  grouping resource-usage-request {
+    description
+      "Information model capturing available parameters to make a resource
+       usage request.";
+    reference "OPNFV-PROMISE, Section 3.4.1";
+
+    uses temporal-resource-collection {
+      refine elements {
+        description
+          "Reference to a list of 'pre-existing' resource elements that are
+         required for fulfillment of the resource-usage-request.
+
+         It can contain any instance derived from ResourceElement,
+         such as ServerInstances or even other
+         ResourceReservations. If the resource-usage-request is
+         accepted, the ResourceElement(s) listed here will be placed
+         into 'protected' mode as to prevent accidental removal.
+
+         If any of these resource elements become 'unavailable' due to
+         environmental or administrative activity, a notification will
+         be issued informing of the issue.";
+      }
+    }
+
+    leaf zone {
+      description "Optional identifier to an Availability Zone";
+      type instance-identifier { ct:instance-type nfvi:AvailabilityZone; }
+    }
+  }
+
+  grouping query-start-end-window {
+    container window {
+      description "Matches entries that are within the specified start/end time window";
+      leaf start { type yang:date-and-time; }
+      leaf end   { type yang:date-and-time; }
+      leaf scope {
+        type enumeration {
+          enum "exclusive" {
+            description "Matches entries that start AND end within the window";
+          }
+          enum "inclusive" {
+            description "Matches entries that start OR end within the window";
+          }
+        }
+        default "inclusive";
+      }
+    }
+  }
+
+  grouping query-resource-collection {
+    uses query-start-end-window {
+      description "Match for ResourceCollection(s) that are within the specified
+                   start/end time window";
+    }
+    leaf-list without {
+      description "Excludes specified collection identifiers from the result";
+      type instance-identifier { ct:instance-type ResourceCollection; }
+    }
+    leaf show-utilization { type boolean; default true; }
+    container elements {
+      leaf-list some {
+        description "Query for ResourceCollection(s) that contain some or more of
+                     these element(s)";
+        type instance-identifier { ct:instance-type nfvi:ResourceElement; }
+      }
+      leaf-list every {
+        description "Query for ResourceCollection(s) that contain all of
+                     these element(s)";
+        type instance-identifier { ct:instance-type nfvi:ResourceElement; }
+      }
+    }
+  }
+
+  grouping common-intent-output {
+    leaf result {
+      type enumeration {
+        enum "ok";
+        enum "conflict";
+        enum "error";
+      }
+    }
+    leaf message { type string; }
+  }
+
+  grouping utilization-output {
+    list utilization {
+      key 'timestamp';
+      leaf timestamp { type yang:date-and-time; }
+      leaf count { type int16; }
+      container capacity { uses nfvi:resource-capacity; }
+    }
+  }
+
+  ct:complex-type ResourceCollection {
+    ct:extends nfvi:ResourceContainer;
+    ct:abstract true;
+
+    description
+      "Describes an abstract ResourceCollection data model, which represents
+       a grouping of capacity and elements available during a given
+       window in time which must be extended by other resource
+       collection related models";
+
+    leaf start { type yang:date-and-time; }
+    leaf end   { type yang:date-and-time; }
+
+    leaf active {
+      config false;
+      description
+        "Provides current state of this record whether it is enabled and within
+         specified start/end time";
+      type boolean;
+    }
+  }
+
+  ct:complex-type ResourcePool {
+    ct:extends ResourceCollection;
+
+    description
+      "Describes an instance of an active ResourcePool record, which
+       represents total available capacity and elements from a given
+       source.";
+
+    leaf source {
+      type instance-identifier {
+        ct:instance-type nfvi:ResourceContainer;
+        require-instance true;
+      }
+      mandatory true;
+    }
+
+    refine elements {
+      // following 'must' statement applies to each element
+      // NOTE: just a non-working example for now...
+      must "boolean(/source/elements/*[@id=id])" {
+        error-message "One or more of the ResourceElement(s) does not exist in
+                       the provider to be reserved";
+      }
+    }
+  }
+
+  ct:complex-type ResourceReservation {
+    ct:extends ResourceCollection;
+
+    description
+      "Describes an instance of an accepted resource reservation request,
+       created usually as a result of 'create-reservation' request.
+
+       A ResourceReservation is a derived instance of a generic
+       ResourceCollection which has additional parameters to map the
+       pool(s) that were referenced to accept this reservation as well
+       as to track allocations made referencing this reservation.
+
+       Contains the capacities of various resource attributes being
+       reserved along with any resource elements that are needed to be
+       available at the time of allocation(s).";
+
+    reference "OPNFV-PROMISE, Section 3.4.1";
+
+    leaf created-on  { type yang:date-and-time; config false; }
+    leaf modified-on { type yang:date-and-time; config false; }
+
+    leaf-list pools {
+      config false;
+      description
+        "Provides list of one or more pools that were referenced for providing
+         the requested resources for this reservation.  This is an
+         important parameter for informing how/where allocation
+         requests can be issued using this reservation since it is
+         likely that the total reserved resource capacity/elements are
+         made availble from multiple sources.";
+      type instance-identifier {
+        ct:instance-type ResourcePool;
+        require-instance true;
+      }
+    }
+
+    container remaining {
+      config false;
+      description
+        "Provides visibility into total remaining capacity for this
+         reservation based on allocations that took effect utilizing
+         this reservation ID as a reference.";
+
+      uses nfvi:resource-capacity;
+    }
+
+    leaf-list allocations {
+      config false;
+      description
+        "Reference to a collection of consumed allocations referencing
+         this reservation.";
+      type instance-identifier {
+        ct:instance-type ResourceAllocation;
+        require-instance true;
+      }
+    }
+  }
+
+  ct:complex-type ResourceAllocation {
+    ct:extends ResourceCollection;
+
+    description
+      "A ResourceAllocation record denotes consumption of resources from a
+       referenced ResourcePool.
+
+       It does not reflect an accepted request but is created to
+       represent the actual state about the ResourcePool. It is
+       created once the allocation(s) have successfully taken effect
+       on the 'source' of the ResourcePool.
+
+       The 'priority' state indicates the classification for dealing
+       with resource starvation scenarios. Lower priority allocations
+       will be forcefully terminated to allow for higher priority
+       allocations to be fulfilled.
+
+       Allocations without reference to an existing reservation will
+       receive the lowest priority.";
+
+    reference "OPNFV-PROMISE, Section 3.4.3";
+
+    leaf reservation {
+      description "Reference to an existing reservation identifier (optional)";
+
+      type instance-identifier {
+        ct:instance-type ResourceReservation;
+        require-instance true;
+      }
+    }
+
+    leaf pool {
+      description "Reference to an existing resource pool from which allocation is drawn";
+
+      type instance-identifier {
+        ct:instance-type ResourcePool;
+        require-instance true;
+      }
+    }
+
+    container instance-ref {
+      config false;
+      description
+        "Reference to actual instance identifier of the provider/server
+        for this allocation";
+      leaf provider {
+        type instance-identifier { ct:instance-type ResourceProvider; }
+      }
+      leaf server { type yang:uuid; }
+    }
+
+    leaf priority {
+      config false;
+      description
+        "Reflects current priority level of the allocation according to
+         classification rules";
+      type enumeration {
+        enum "high"   { value 1; }
+        enum "normal" { value 2; }
+        enum "low"    { value 3; }
+      }
+      default "normal";
+    }
+  }
+
+  ct:complex-type ResourceProvider {
+    ct:extends nfvi:ResourceContainer;
+
+    key "name";
+    leaf token { type string; mandatory true; }
+
+    container services { // read-only
+      config false;
+      container compute {
+        leaf endpoint { type inet:uri; }
+        ct:instance-list flavors { ct:instance-type nfvi:ComputeFlavor; }
+      }
+    }
+
+    leaf-list pools {
+      config false;
+      description
+        "Provides list of one or more pools that are referencing this provider.";
+
+      type instance-identifier {
+        ct:instance-type ResourcePool;
+        require-instance true;
+      }
+    }
+  }
+
+  // MAIN CONTAINER
+  container promise {
+
+    uses resource-utilization {
+      description "Describes current state info about capacity utilization info";
+
+      augment "capacity/total"     { uses nfvi:resource-capacity; }
+      augment "capacity/reserved"  { uses nfvi:resource-capacity; }
+      augment "capacity/usage"     { uses nfvi:resource-capacity; }
+      augment "capacity/available" { uses nfvi:resource-capacity; }
+    }
+
+    ct:instance-list providers {
+      if-feature multi-provider;
+      description "Aggregate collection of all registered ResourceProvider instances
+                   for Promise resource management service";
+      ct:instance-type ResourceProvider;
+    }
+
+    ct:instance-list pools {
+      if-feature reservation-service;
+      description "Aggregate collection of all ResourcePool instances";
+      ct:instance-type ResourcePool;
+    }
+
+    ct:instance-list reservations {
+      if-feature reservation-service;
+      description "Aggregate collection of all ResourceReservation instances";
+      ct:instance-type ResourceReservation;
+    }
+
+    ct:instance-list allocations {
+      description "Aggregate collection of all ResourceAllocation instances";
+      ct:instance-type ResourceAllocation;
+    }
+
+    container policy {
+      container reservation {
+        leaf max-future-start-range {
+          description
+            "Enforce reservation request 'start' time is within allowed range from now";
+          type uint16 { range 0..365; }
+          units "days";
+        }
+        leaf max-future-end-range {
+          description
+            "Enforce reservation request 'end' time is within allowed range from now";
+          type uint16 { range 0..365; }
+          units "days";
+        }
+        leaf max-duration {
+          description
+            "Enforce reservation duration (end-start) does not exceed specified threshold";
+          type uint16;
+          units "hours";
+          default 8760; // for now cap it at max one year as default
+        }
+        leaf expiry {
+          description
+            "Duration in minutes from start when unallocated reserved resources
+             will be released back into the pool";
+          type uint32;
+          units "minutes";
+        }
+      }
+    }
+  }
+
+  //-------------------
+  // INTENT INTERFACE
+  //-------------------
+
+  // RESERVATION INTENTS
+  rpc create-reservation {
+    if-feature reservation-service;
+    description "Make a request to the reservation system to reserve resources";
+    input {
+      uses resource-usage-request;
+    }
+    output {
+      uses common-intent-output;
+      leaf reservation-id {
+        type instance-identifier { ct:instance-type ResourceReservation; }
+      }
+    }
+  }
+
+  rpc update-reservation {
+    description "Update reservation details for an existing reservation";
+    input {
+      leaf reservation-id {
+        type instance-identifier {
+          ct:instance-type ResourceReservation;
+          require-instance true;
+        }
+        mandatory true;
+      }
+      uses resource-usage-request;
+    }
+    output {
+      uses common-intent-output;
+    }
+  }
+
+  rpc cancel-reservation {
+    description "Cancel the reservation and be a good steward";
+    input {
+      leaf reservation-id {
+        type instance-identifier { ct:instance-type ResourceReservation; }
+        mandatory true;
+      }
+    }
+    output {
+      uses common-intent-output;
+    }
+  }
+
+  rpc query-reservation {
+    if-feature reservation-service;
+    description "Query the reservation system to return matching reservation(s)";
+    input {
+      leaf zone { type instance-identifier { ct:instance-type nfvi:AvailabilityZone; } }
+      uses query-resource-collection;
+    }
+    output {
+      leaf-list reservations { type instance-identifier
+                               { ct:instance-type ResourceReservation; } }
+      uses utilization-output;
+    }
+  }
+
+  // CAPACITY INTENTS
+  rpc increase-capacity {
+    description "Increase total capacity for the reservation system
+                 between a window in time";
+    input {
+      uses temporal-resource-collection;
+      leaf source {
+        type instance-identifier {
+          ct:instance-type nfvi:ResourceContainer;
+        }
+      }
+    }
+    output {
+      uses common-intent-output;
+      leaf pool-id {
+        type instance-identifier { ct:instance-type ResourcePool; }
+      }
+    }
+  }
+
+  rpc decrease-capacity {
+    description "Decrease total capacity for the reservation system
+                 between a window in time";
+    input {
+      uses temporal-resource-collection;
+      leaf source {
+        type instance-identifier {
+          ct:instance-type nfvi:ResourceContainer;
+        }
+      }
+    }
+    output {
+      uses common-intent-output;
+      leaf pool-id {
+        type instance-identifier { ct:instance-type ResourcePool; }
+      }
+    }
+  }
+
+  rpc query-capacity {
+    description "Check available capacity information about a specified
+                 resource collection";
+    input {
+      leaf capacity {
+        type enumeration {
+          enum 'total';
+          enum 'reserved';
+          enum 'usage';
+          enum 'available';
+        }
+        default 'available';
+      }
+      leaf zone { type instance-identifier { ct:instance-type nfvi:AvailabilityZone; } }
+      uses query-resource-collection;
+      // TBD: additional parameters for query-capacity
+    }
+    output {
+      leaf-list collections { type instance-identifier
+                              { ct:instance-type ResourceCollection; } }
+      uses utilization-output;
+    }
+  }
+
+  // ALLOCATION INTENTS (should go into VIM module in the future)
+  rpc create-instance {
+    description "Create an instance of specified resource(s) utilizing capacity
+                 from the pool";
+    input {
+      leaf provider-id {
+        if-feature multi-provider;
+        type instance-identifier { ct:instance-type ResourceProvider;
+                                   require-instance true; }
+      }
+      leaf name   { type string; mandatory true; }
+      leaf image  {
+        type reference-identifier;
+        mandatory true;
+      }
+      leaf flavor {
+        type reference-identifier;
+        mandatory true;
+      }
+      leaf-list networks {
+        type reference-identifier;
+        description "optional, will assign default network if not provided";
+      }
+
+      // TODO: consider supporting a template-id (such as HEAT) for more complex instantiation
+
+      leaf reservation-id {
+        type instance-identifier { ct:instance-type ResourceReservation;
+                                   require-instance true; }
+      }
+    }
+    output {
+      uses common-intent-output;
+      leaf instance-id {
+        type instance-identifier { ct:instance-type ResourceAllocation; }
+      }
+    }
+  }
+
+  rpc destroy-instance {
+    description "Destroy an instance of resource utilization and release it
+                 back to the pool";
+    input {
+      leaf instance-id {
+        type instance-identifier { ct:instance-type ResourceAllocation;
+                                   require-instance true; }
+      }
+    }
+    output {
+      uses common-intent-output;
+    }
+  }
+
+  // PROVIDER INTENTS (should go into VIM module in the future)
+  rpc add-provider {
+    description "Register a new resource provider into reservation system";
+    input {
+      leaf provider-type {
+        description "Select a specific resource provider type";
+        mandatory true;
+        type enumeration {
+          enum openstack;
+          enum hp;
+          enum rackspace;
+          enum amazon {
+            status planned;
+          }
+          enum joyent {
+            status planned;
+          }
+          enum azure {
+            status planned;
+          }
+        }
+        default openstack;
+      }
+      uses mano:provider-credentials {
+        refine endpoint {
+          default "http://localhost:5000/v2.0/tokens";
+        }
+      }
+      container tenant {
+        leaf id { type string; }
+        leaf name { type string; }
+      }
+    }
+    output {
+      uses common-intent-output;
+      leaf provider-id {
+        type instance-identifier { ct:instance-type ResourceProvider; }
+      }
+    }
+  }
+
+  // TODO...
+  notification reservation-event;
+  notification capacity-event;
+  notification allocation-event;
+  }
diff --git a/docs/development/requirements/summary.rst b/docs/development/requirements/summary.rst
new file mode 100644
index 0000000..fcf10d1
--- /dev/null
+++ b/docs/development/requirements/summary.rst
@@ -0,0 +1,27 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+======================
+Summary and conclusion
+======================
+
+Resource Reservation and Resource Capacity Management are features to be
+supported by the VIM and exposed to the consumer via the VIM NBI. These
+features have been specified by ETSI NFV.
+
+This document has described several use cases and corresponding high level
+flows where Resource Reservation and Capacity Management are of great benefit
+for the consumer of the virtualised resource management interface: the NFVO or
+the VNFM. The use cases include:
+
+* Notification of changes in capacity in the NFVI
+* Query of available resource capacity
+* Reservation of a resource or set of resources for immediate use
+* Reservation of a resource or set of resources for future use
+
+The Promise project has performed a gap analysis in order to fulfill the
+required functionality. Based on the gap analysis an implementation plan and
+way forward has been proposed, including a possible design architecture and
+high level information model. Immediate next steps of this project is to
+deliver a working Proof-of-Concepts (PoC) and engage upstream communities to
+fill out the gaps identified by Promise.
diff --git a/docs/development/requirements/supported_apis.rst b/docs/development/requirements/supported_apis.rst
new file mode 100644
index 0000000..40cba8d
--- /dev/null
+++ b/docs/development/requirements/supported_apis.rst
@@ -0,0 +1,608 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+ANNEX C: Supported APIS
+=======================
+
+Add Provider
+------------
+
+Register a new resource provider (e.g. OpenStack) into reservation system.
+
+Request parameters
+
+============================ =========== ==============================================
+Name                         Type        Description
+============================ =========== ==============================================
+provider-type                Enumeration Name of the resource provider
+endpoint                     URI         Targer URL end point for the resource provider
+username                     String      User name
+password                     String      Password
+region                       String      Specified region for the provider
+tenant.id                    String      Id of the tenant
+tenant.name                  String      Name of the tenant
+============================ =========== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name                         Type        Description
+============================ =========== ==============================================
+provider-id                  String      Id of the new resource provider
+result                       Enumeration Result info
+============================ =========== ==============================================
+
+.. http:post:: /add-provider
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      POST /add-provider HTTP/1.1
+      Accept: application/json
+
+      {
+        "provider-type": "openstack",
+        "endpoint": "http://10.0.2.15:5000/v2.0/tokens",
+        "username": "promise_user",
+        "password": "******",
+        "tenant": {
+           "name": "promise"
+        }
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+        "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302",
+        "result": "ok"
+      }
+
+Create Reservation
+------------------
+
+Make a request to the reservation system to reserve resources.
+
+Request parameters
+
+============================ =============== ==============================================
+Name                         Type            Description
+============================ =============== ==============================================
+zone                         String          Id to an availability zone
+start                        DateTime        Timestamp when the consumption of reserved
+                                             resources can begin
+end                          DateTime        Timestamp when the consumption of reserved
+                                             resources should end
+capacity.cores               int16           Amount of cores to be reserved
+capacity.ram                 int32           Amount of RAM to be reserved
+capacity.instances           int16           Amount of instances to be reserved
+capacity.addresses           int32           Amount of public IP addresses to be reserved
+elements                     ResourceElement List of pre-existing resource elements
+                                             to be reserved
+============================ =============== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name                         Type        Description
+============================ =========== ==============================================
+reservation-id               String      Id of the reservation
+result                       Enumeration Result info
+message                      String      Output message
+============================ =========== ==============================================
+
+.. http:post:: /create-reservation
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      POST /create-reservation HTTP/1.1
+      Accept: application/json
+
+      {
+         "capacity": {
+            "cores": "5",
+            "ram": "25600",
+            "addresses": "3",
+            "instances": "3"
+         },
+         "start": "2016-02-02T00:00:00Z",
+         "end": "2016-02-03T00:00:00Z"
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+        "reservation-id": "269b2944-9efc-41e0-b067-6898221e8619",
+        "result": "ok",
+        "message": "reservation request accepted"
+      }
+
+Update Reservation
+------------------
+
+Update reservation details for an existing reservation.
+
+Request parameters
+
+============================ =============== ==============================================
+Name                         Type            Description
+============================ =============== ==============================================
+reservation-id               String          Id of the reservation to be updated
+zone                         String          Id to an availability zone
+start                        DateTime        Updated timestamp when the consumption of
+                                             reserved resources can begin
+end                          DateTime        Updated timestamp when the consumption of
+                                             reserved resources should end
+capacity.cores               int16           Updated amount of cores to be reserved
+capacity.ram                 int32           Updated amount of RAM to be reserved
+capacity.instances           int16           Updated amount of instances to be reserved
+capacity.addresses           int32           Updated amount of public IP addresses
+                                             to be reserved
+elements                     ResourceElement Updated list of pre-existing resource elements
+                                             to be reserved
+============================ =============== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name                         Type        Description
+============================ =========== ==============================================
+result                       Enumeration Result info
+message                      String      Output message
+============================ =========== ==============================================
+
+.. http:post:: /update-reservation
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      POST /update-reservation HTTP/1.1
+      Accept: application/json
+
+      {
+         "reservation-id": "269b2944-9efv-41e0-b067-6898221e8619",
+         "capacity": {
+            "cores": "1",
+            "ram": "5120",
+            "addresses": "1",
+            "instances": "1"
+         }
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+        "result": "ok",
+        "message": "reservation update successful"
+      }
+
+Cancel Reservation
+------------------
+
+Cancel the reservation.
+
+Request parameters
+
+============================ =============== ==============================================
+Name                         Type            Description
+============================ =============== ==============================================
+reservation-id               String          Id of the reservation to be canceled
+============================ =============== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name                         Type        Description
+============================ =========== ==============================================
+result                       Enumeration Result info
+message                      String      Output message
+============================ =========== ==============================================
+
+.. http:post:: /cancel-reservation
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      POST /cancel-reservation HTTP/1.1
+      Accept: application/json
+
+      {
+        "reservation-id": "269b2944-9efv-41e0-b067-6898221e8619"
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+        "result": "ok",
+        "message": "reservation canceled"
+      }
+
+Query Reservation
+-----------------
+
+Query the reservation system to return matching reservation(s).
+
+Request parameters
+
+============================ ================== ==============================================
+Name                         Type               Description
+============================ ================== ==============================================
+zone                         String             Id to an availability zone
+show-utilization             Boolean            Show capacity utilization
+without                      ResourceCollection Excludes specified collection identifiers
+                                                from the result
+elements.some                ResourceElement    Query for ResourceCollection(s) that contain
+                                                some or more of these element(s)
+elements.every               ResourceElement    Query for ResourceCollection(s) that contain
+                                                all of these element(s)
+window.start                 DateTime           Matches entries that are within the specified
+                                                start/end window
+window.end                   DateTime
+wndow.scope                  Enumeration        Matches entries that start {and/or} end
+                                                within the time window
+============================ ================== ==============================================
+
+Response parameters
+
+============================ =================== ================================
+Name                         Type                Description
+============================ =================== ================================
+reservations                 ResourceReservation List of matching reservations
+utilization                  CapacityUtilization Capacity utilization over time
+============================ =================== ================================
+
+.. http:post:: /query-reservation
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      POST /query-reservation HTTP/1.1
+      Accept: application/json
+
+      {
+         "show-utilization": false,
+         "window": {
+            "start": "2016-02-01T00:00:00Z",
+            "end": "2016-02-04T00:00:00Z"
+         }
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+        "reservations": [
+          "269b2944-9efv-41e0-b067-6898221e8619"
+        ],
+        "utilization": []
+      }
+
+Create Instance
+---------------
+
+Create an instance of specified resource(s) utilizing capacity from the pool.
+
+Request parameters
+
+============================ =============== ==============================================
+Name                         Type            Description
+============================ =============== ==============================================
+provider-id                  String          Id of the resource provider
+reservation-id               String          Id of the resource reservation
+name                         String          Name of the instance
+image                        String          Id of the image
+flavor                       String          Id of the flavor
+networks                     Uuid            List of network uuids
+============================ =============== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name                         Type        Description
+============================ =========== ==============================================
+instance-id                  String      Id of the instance
+result                       Enumeration Result info
+message                      String      Output message
+============================ =========== ==============================================
+
+.. http:post:: /create-instance
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      POST /create-instance HTTP/1.1
+      Accept: application/json
+
+      {
+        "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302",
+        "name": "vm1",
+        "image": "ddffc6f5-5c86-4126-b0fb-2c71678633f8",
+        "flavor": "91bfdf57-863b-4b73-9d93-fc311894b902"
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+        "instance-id": "82572779-896b-493f-92f6-a63008868250",
+        "result": "ok",
+        "message": "created-instance request accepted"
+      }
+
+Destroy Instance
+----------------
+
+Destroy an instance of resource utilization and release it back to the pool.
+
+Request parameters
+
+============================ =============== ==============================================
+Name                         Type            Description
+============================ =============== ==============================================
+instance-id                  String          Id of the instance to be destroyed
+============================ =============== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name                         Type        Description
+============================ =========== ==============================================
+result                       Enumeration Result info
+message                      String      Output message
+============================ =========== ==============================================
+
+.. http:post:: /destroy-instance
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      POST /destroy-instance HTTP/1.1
+      Accept: application/json
+
+      {
+         "instance-id": "82572779-896b-493f-92f6-a63008868250"
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+        "result": "ok",
+        "message": "instance destroyed and resource released back to pool"
+      }
+
+Decrease Capacity
+-----------------
+
+Decrease total capacity for the reservation system for a given time window.
+
+Request parameters
+
+============================ =============== ==============================================
+Name                         Type            Description
+============================ =============== ==============================================
+source                       String          Id of the resource container
+start                        DateTime        Start/end defines the time window when total
+                                             capacity is decreased
+end                          DateTime
+capacity.cores               int16           Decreased amount of cores
+capacity.ram                 int32           Decreased amount of RAM
+capacity.instances           int16           Decreased amount of instances
+capacity.addresses           int32           Decreased amount of public IP addresses
+============================ =============== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name                         Type        Description
+============================ =========== ==============================================
+pool-id                      String      Id of the resource pool
+result                       Enumeration Result info
+message                      String      Output message
+============================ =========== ==============================================
+
+.. http:post:: /decrease-capacity
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      POST /decrease-capacity HTTP/1.1
+      Accept: application/json
+
+      {
+         "source": "ResourcePool:4085f0da-8030-4252-a0ff-c6f93870eb5f",
+         "capacity": {
+            "cores": "3",
+            "ram": "5120",
+            "addresses": "1"
+         }
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+         "pool-id": "c63b2a41-bcc6-42f6-8254-89d633e1bd0b",
+         "result": "ok",
+         "message": "capacity decrease successful"
+      }
+
+Increase Capacity
+-----------------
+
+Increase total capacity for the reservation system for a given time window.
+
+Request parameters
+
+============================ =============== ==============================================
+Name                         Type            Description
+============================ =============== ==============================================
+source                       String          Id of the resource container
+start                        DateTime        Start/end defines the time window when total
+                                             capacity is increased
+end                          DateTime
+capacity.cores               int16           Increased amount of cores
+capacity.ram                 int32           Increased amount of RAM
+capacity.instances           int16           Increased amount of instances
+capacity.addresses           int32           Increased amount of public IP addresses
+============================ =============== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name                         Type        Description
+============================ =========== ==============================================
+pool-id                      String      Id of the resource pool
+result                       Enumeration Result info
+message                      String      Output message
+============================ =========== ==============================================
+
+.. http:post:: /increase-capacity
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      POST /increase-capacity HTTP/1.1
+      Accept: application/json
+
+      {
+         "source": "ResourceProvider:f6f13fe3-0126-4c6d-a84f-15f1ab685c4f",
+         "capacity": {
+             "cores": "20",
+             "ram": "51200",
+             "instances": "10",
+             "addresses": "10"
+         }
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+         "pool-id": "279217a4-7461-4176-bf9d-66770574ca6a",
+         "result": "ok",
+         "message": "capacity increase successful"
+      }
+
+Query Capacity
+--------------
+
+Query for capacity information about a specified resource collection.
+
+Request parameters
+
+============================ ================== ==============================================
+Name                         Type               Description
+============================ ================== ==============================================
+capacity                     Enumeration        Return total or reserved or available or
+                                                usage capacity information
+zone                         String             Id to an availability zone
+show-utilization             Boolean            Show capacity utilization
+without                      ResourceCollection Excludes specified collection identifiers
+                                                from the result
+elements.some                ResourceElement    Query for ResourceCollection(s) that contain
+                                                some or more of these element(s)
+elements.every               ResourceElement    Query for ResourceCollection(s) that contain
+                                                all of these element(s)
+window.start                 DateTime           Matches entries that are within the specified
+                                                start/end window
+window.end                   DateTime
+window.scope                 Enumeration        Matches entries that start {and/or} end
+                                                within the time window
+============================ ================== ==============================================
+
+Response parameters
+
+============================ =================== ================================
+Name                         Type                Description
+============================ =================== ================================
+collections                  ResourceCollection  List of matching collections
+utilization                  CapacityUtilization Capacity utilization over time
+============================ =================== ================================
+
+.. http:post:: /query-capacity
+   :noindex:
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      POST /query-capacity HTTP/1.1
+      Accept: application/json
+
+      {
+        "show-utilization": false
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 201 CREATED
+      Content-Type: application/json
+
+      {
+        "collections": [
+          "ResourcePool:279217a4-7461-4176-bf9d-66770574ca6a"
+        ],
+        "utilization": []
+      }
+
diff --git a/docs/development/requirements/usecase.rst b/docs/development/requirements/usecase.rst
new file mode 100644
index 0000000..bdf8888
--- /dev/null
+++ b/docs/development/requirements/usecase.rst
@@ -0,0 +1,121 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+=======================
+Use cases and scenarios
+=======================
+
+Use cases
+=========
+
+Resource reservation is a basic feature in any virtualization-based network
+operation. In order to perform such resource reservation from NFVO to VIM, NFVI
+capacity information is also necessary at the NFVO side. Below, four use cases
+to show typical requirements and solutions for capacity management and resource
+reservation is presented. A typical use case as considered for the Brahmaputra
+release is described in :ref:`uc-brahmaputra`.
+
+#.  Resource capacity management
+#.  Resource reservation for immediate use
+#.  Resource reservation for future use
+#.  Co-existence of reservations and allocation requests without reservation
+
+Resource capacity management
+----------------------------
+
+NFVO takes the first decision on in which NFVI it would instantiate a VNF. Along
+with NFVIs resource attributes (e.g. availability of hardware accelerators,
+particular CPU architectures etc.), NFVO needs to know available capacity of an
+NFVI in order to make an informed decision on selecting a particular NFVI. Such
+capacity information shall be in a coarser granularity than the respective VIM,
+as VIM maintains capacity information of its NFVI in fine details.  However a
+very coarse granularity, like simply the number of available virtual CPU cores,
+may not be sufficient. In order to allow the NFVO to make well founded
+allocation decisions, an appropriate level to expose the available capacity may
+be per flavor. Capacity information may be required for the complete NFVI, or
+per partition or availability zone, or other granularities. Therefore, VIM
+requires to inform the NFVO about available capacity information regarding its
+NFVI at a pre-determined abstraction, either by a query-response, or in an
+event-based, or in a periodical way.
+
+Resource reservation for immediate use
+--------------------------------------
+
+Reservation is inherently for the future. Even if some reserved resources are to
+be consumed instantly, there is a network latency between the issuance of a
+resource reservation request from the NFVO, a response from the VIM, and actual
+allocation of the requested resources to a VNF/VNFM. Within such latency,
+resource capacity in the NFVI in question could change, e.g., due to failure,
+allocation to a different request. Therefore, the response from a VIM to the
+NFVO to a resource reservation request for immediate use should have a validity
+period which shows until when this VIM can hold the requested resources. During
+this time, the NFVO should proceed to allocation if it wishes to consume the
+reserved requested. If allocation is not performed within the validity period,
+the response from VIM for a particular resource reservation request becomes
+invalid and VIM is not liable to provide those resources to NFVO/VNFM anymore.
+Reservations requests for immediate use do not have a start time but may have
+an end time.
+
+Resource reservation for future use
+-----------------------------------
+
+Network operators may want to reserve extra resources for future use. Such
+necessity could arise from predicted congestion in telecom nodes e.g. due to
+local traffic spikes for concerts, natural disasters etc. In such a case, the
+NFVO, while sending a resource reservation request to the VIM, shall include a
+start time (and an end time if necessary). The start time indicates at what
+time the reserved resource shall be available to a designated consumer e.g. a
+VNF/VNFM. Here, the requirement is that the reserved resources shall be
+available when the start time arrives. After the start time has arrived, the
+reserved resources are allocated to the designated consumer(s). An explicit
+allocation request is needed. How actually these requested resources are held
+by the VIM for the period in between the arrival of the resource reservation
+request and the actual allocation is outside the scope of this requirement
+project.
+
+Co-existence of reservations and allocation requests without reservation
+------------------------------------------------------------------------
+
+In a real environment VIM will have to handle allocation requests without any
+time reference, i.e. time-unbound, together with time-bound reservations and
+allocation requests with an explicitly indicated end-time. A granted
+reservation for the future will effectively reduce the available capacity for
+any new time-unbound allocation request. The consequence is that reservations,
+even those far in the future, may result in denial of service for new
+allocation requests.
+
+To alleviate this problem several approaches can be taken. They imply an
+implicit or explicit priority scheme:
+
+* Allocation requests without reservation and which are time-unbound will be
+  granted resources in a best-effort way: if there is instant capacity, but the
+  resources may be later withdrawn due to the start time of a previously
+  granted reservation
+* Both allocation requests and reservation requests contain a priority which
+  may be related to SLAs and contractual conditions between the tenant and the
+  NFVI provider. Interactions may look like:
+
+  * A reservation request for future use may cancel another, not yet
+    started, reservation with lower priority
+  * An allocation request without reservations and time-unbound [#unbound]_
+    may be granted resources and prevent a future reservation with lower
+    priority from getting resources at start time
+  * A reservation request may result in terminating resources allocated to a
+    request with no reservation, if the latter has lower priority
+
+.. [#unbound] In this case, the consumer (VNFM or NFVO) requests to immediately
+              instantiate and assign virtualized resources without having
+              reserved the resources beforehand
+
+Scenarios
+=========
+
+This section describes the expected behavior of the system in different
+scenarios.
+
+As we are targeting a cloud platform with the above use cases, it is crucial to
+keep the flexibility in the system. By this means it is hard to explicitely
+block hardware resources for the future and ensure their availablility for
+allocation therefore it can happen that the reservation plan cannot be fulfilled
+due to certain changes in the underlying environment. We need to ensure that we
+are prepared for error and edge cases during the design period.