Reservation API

The Reservation API uses Representational State Transfer (REST) web services that enable you to create, retrieve, update, delete, and work with reservations. You can integrate the API with your other business applications. The API is exposed by the Data Hub component and is located at the following path on the BMC Helix Capacity Optimization Data Hub server: https://<optapi external address>/dh-services/rsv

Before you begin

Ensure that the following requirements are met:

API methods

The following table provides the details of the Reservation API methods:

Resource

Method

URI pattern

Description

Required activity

GET

rsv/reservations/{reservation-id}

Retrieve data for an existing reservation, along with alert status information.

Read access to Reservation API

PUT

rsv/reservations/{reservation-id}

Update an existing reservation and perform the placement, if items are specified. You can update an existing reservation to do the placement, select a pool, update the resources and update the status of the reservation.

Write access to Reservation API

POST

rsv/reservations

Create a new reservation and perform the placement, if items are specified. Alert status information is also listed.

Write access to Reservation API

DELETE

rsv/reservations/{reservation-id}

Delete an existing reservation.

Write access to Reservation API

POST

rsv/search/reservations

Search for reservations that match query criteria.

Read access to Reservation API

GET

rsv/reservations/{reservation-id}/items/{item-id}

Retrieve the details of a reservation item.

Read access to Reservation API

PUT

rsv/reservations/{reservation-id}/items/{item-id}

Update a reservation item.

Write access to Reservation API

DELETE

rsv/reservations/{reservation-id}/items/{item-id}

Delete a reservation item.

Write access to Reservation API

GET

rsv/offboardings/{offboarding-id}

Retrieve the details of an existing offboarding.

Read access to Reservation API

PUT

rsv/offboardings/{offboarding-id}

Update an existing offboarding.

Write access to Reservation API

POST

rsv/offboardings

Create a new offboarding.

Write access to Reservation API

DELETE

rsv/offboardings/{offboarding-id}

Delete an existing offboarding.

Write access to Reservation API

POST

rsv/search/offboardings

Search for an existing offboarding based on query criteria.

Read access to Reservation API

GET

rsv/onboardings/{onboarding-id}

Retrieve the details of an existing onboarding.

Read access to Reservation API

PUT

rsv/onboardings/{onboarding-id}

Update an existing onboarding.

Write access to Reservation API

POST

rsv/onboardings

Create a new onboarding.

Write access to Reservation API

DELETE

rsv/onboardings/{onboarding-id}

Delete an existing onboarding.

Write access to Reservation API

POST

rsv/search/onboardings

Search for an existing onboarding based on query criteria.

Read access to Reservation API

GET

rsv/reservationTargets/{container-id}

Retrieve the details of a reservation target.

Read access to Reservation API

POST

rsv/search/reservationtargets

Search for a reservation target based on query criteria.

Read access to Reservation API

GET

rsv/capacitypools/{pool-id}

Retrieve the details of an existing capacity pool.

Read access to Reservation API

POST

rsv/search/capacitypools

Search for a capacity pool based on query criteria.

Read access to Reservation API

GET

rsv/tenants/{tenant-id}

Retrieve tenant details with alert status information.

Read access to Reservation API

POST

rsv/search/tenants

Search for tenants based on query criteria.

Read access to Reservation API

GET

{{code language="none"}}
rsv/systemtemplates/{template-id}
{{/code}}

Retrieve the details of a system template.

Read access to Reservation API

PUT

rsv/systemtemplates/{template-id}

Update a system template.

Write access to Reservation API

POST

rsv/systemtemplates

Create a new system template.

Write access to Reservation API

DELETE

rsv/systemtemplates/{template-id}

Delete a system template.

Write access to Reservation API

POST

rsv/search/systemtemplates

Search for a system template based on query criteria.

Read access to Reservation API

GET

rsv/servicetemplates/{template-id}

Retrieve the details of a service template.

Read access to Reservation API

POST

rsv/search/servicetemplates

Search for a service template based on query criteria.

Read access to Reservation API


Back to Top 

Reservation

Info
  • For a reservation with resources, placement is not possible. You can use PUT call after you create the reservation, to place it.
  • If a Reservation is placed, with POST or PUT, the status could stay PROCESSING for a while, until the Auto Forecasting Service (AFS) processes the Reservation. The AFS runs every five minutes. So you may have to wait for maximum five minutes, to see the updated status:
    • REQUEST_COMMIT
    • REQUEST_PENDING
    • REQUEST_REALIZE
    • REQUEST_EXPIRE
    • REQUEST_DECLINE
  • A reservation can be automatically committed only after you perform the placement. Even if you create a reservation with auto-commit


About reservation resources

 On creating a reservation, you can specify items to be placed by specifying one of the following Reservation resources:

  • resourceTemplates: specifying number of instances based on templates. resourceTemplates is an array of objects, each defining a reservation template associated to a reservation. They contain the following fields:
    • systemTemplateLookup, serviceTemplateLookup. Use one of these properties to define a template to associate to the reservation.
      • systemTemplateLookup specifies the id or the name or a list of lookup fields to identify a system template.
      • serviceTemplateLookup specifies the id or the name or a list of lookup fields to identify a system template.
    • numItems. The number of reservation items to instantiate using this system/service template.
  • resourceSpecs: specifying number of instances based on custom resources. resourceSpecs is an array of objects, each defining a custom resource associated to a reservation. They contain the following fields:
    • name. The name of the custom resource.
    • numItems. The number of reservation items to instantiate using this custom resource.
    • enttypenm. The type of the custom resource, e.g. Virtual Machine.
    • cpuCores. The number of CPU cores used by the custom resource.
    • cpuTotalMhz. The number of total MHz used by the custom resource.
    • emTotal. The total amount of memory used by the custom resource.
    • storageTotal. The total amount of disk space used by the custom resource.
  • items: directly listing the using items that are an array of objects, each defining an item of a reservation. They contain the following fields:
    • name: name of the item
    • systemTemplateLookup/serviceTemplateLookup: lookup of the template used to build a reservation item

Get data for a reservation

Retrieves data for an existing reservation, along with alert status information.

HTTP method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

GET

rsv/reservations/{reservation-id}

Reservation ID

 

 

Sample request and response files

Retrieving data for an existing reservation
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/reservations/{reservation-id}
Sample response
{
   "href": "http://.../rsv/reservations/{reservation-id}",
   "id": 10155,
   "name": "my_rsv",
   "startDate": "15/01/2015",
   "status": "COMMITTED",
   "alertstatus": [
         "BCO_RSV_ERR114: This Reservation will be infeasible
          because capacity will be exhausted"
      ],
   ...     
   "items": [            {
               "href": "http://.../rsv/reservations/{reservation-id}/items/354",
               "id": 354,
               "name": "DB_Server",
               "systemTemplate": {
                   "href": "http://.../rsv/systemtemplates/2213",
                   "id": 2213,
                   "name": "DB.server"
               },
               "reservationTarget": {
                   "href": "http://.../rsv/reservationtargets/2714",
                   "id": 2714,
                   "name": "Houston Cluster"
               }
           },
           {
               "href": "http://.../rsv/reservations/{reservation-id}/items/355",
               "id": 355,
               "name": "Web_Server",
               "systemTemplate": {
                   "href": "http://.../rsv/systemtemplates/2214",
                   "id": 2214,
                   "name": "VMware.small"
               },                 
               "reservationTarget": {
                   "href": "http://.../rsv/reservationtargets/442",
                   "id": 442,
                   "name": "Env12"
               }
           }
       ],
       "capacityPools": [
          ...
       ]
   }
}

Back to Top

Update an existing reservation

Updates an existing reservation and does the placement, if items are specified. You can update an existing reservation to do the placement, select a pool, update the resources and update the status of the reservation. 

Method

URI pattern

Required
Request
Parameters

Optional Request Parameters

PUT

rsv/reservations/{reservation-id}
  • Reservation ID
  • Name  
  • Start date
  • Reservation resources (resourceTemplates,
    resourceSpecs, or Items)
  • Lookup fields

 

  • Description 
  • End date 
  • External ID
  • Owner
  • Priority 
  • Probability
  • Capacity Pools
  • Realization Mode
  • High availability


Sample request and response files

Updating a reservation already created given its id and placing its items
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/reservations/{{rsv-id}} 
Sample request
{
 "name": "WEB portal - POC",
 "startDate": "02/06/2016",
 "description": "POC of the new WEB portal that will be released in autumn",
 "items": [
   {
     "id": 876,
     "name": "File Server",
     "systemTemplate": {
       "id": 2526,
       "name": "Large KVM"
     },
      "reservationTargetLookup": {
       "lookupFields": [
           {"lookupField": "NAME","lookupValue": "vh.bco-kvm-icehouse"}
       ]
     }
   }
 ],
 "capacityPools": [
   {
     "capacityPoolLookup": {
       "id": 2180
     }
   }
 ]
}
Sample response
{
"status": "OK",
"message": "The reservation has been successfully updated" “reservation” :
{ {{the updated reservation, as passed in the request payload}} }
}
Updating a reservation adding three new instances of “Small KVM virtual machines”
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/reservations/{{rsv-id}}
Sample request
{
 "name": "ACME new video streaming platform",
 "startDate": "15/10/2016",
 "resources": {
   "resourceTemplates": [
     {
       "numItems": 1,
       "systemTemplate": {
         "id": 2527,
         “name”:”Large VMware VM”
       }
     },
     {
       "enttypenm": "gm:kvm",
       "numItems": 3,
       "systemTemplateLookup": {
                 "lookupFields": [
           {"lookupField": "NAME","lookupValue": " Small KVM "}
       ]
       }
     }
   ]
 },
 "capacityPools": [
   {
     "capacityPoolLookup": {
       "id": 2180
     }
   }
 ]
}
Sample Response
{
"status": "OK",
"message": "The reservation has been successfully updated"
“reservation” : {
{{the updated reservation, as passed in the request payload}}
}
}
Declining a reservation
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/search/reservations/{{rsv-id}}
Sample request
{
 "name": "ACME new video streaming platform",
 "startDate": "15/10/2016",
 “status”: “REQUEST_DECLINE”,
 "resources": {
   "resourceTemplates": [
     {
       "enttypenm": "gm:kvm",
       "numItems": 1,
       "systemTemplate": {
xisting          "id": 2527
       }
     }
   ]
 },
 "capacityPools": [
   {
     "capacityPoolLookup": {
       "id": 2180
     }
   }
 ]
}
 
Sample response
{
"status": "OK",
"message": "The reservation has been successfully updated"
“reservation” : {
{{the updated reservation, as passed in the request payload}}
}
}

Back to Top

Create a new reservation

Creates a new reservation and does the placement, if items are specified. Alert status information is also listed.

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

POST

rsv/reservations
  • Name
  • Start date

  • Reservation resources (resourceTemplates,

    resourceSpecs, or items)

  • Description 
  • End date 
  • External ID 
  • Owner
  • Priority 
  • Probability
  • Capacity Pool(s)
  • Realization Mode
  • High availability

Sample request and response files

Creating a new reservation for two instances of “VMware - virtual machine” template
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/reservations
Sample request
{
 "name": "Billing Service 2.1",
 "startDate": "29/09/2016",
 "endDate": "24/10/2016",
 "description": "reserve new capacity for billing dept. ",
 "owner": "alan",
 "externalid": "BILLING",
 "priority": "MEDIUM",
 "probability": 100,
 "resources": {
   "resourceTemplates": [
     {
       "numItems": 2,
       "systemTemplateLookup": {
         "id": 2191
       }
     }
   ]
 },
 "capacityPools": [
   {
     "capacityPoolLookup": {
       "id": 2172
     }
   }
 ]
} 
Sample response
 {
 "status": "OK",
"message": "The reservation has been successfully created"
“reservation” : {  
 "name": "Billing Service 2.1",
 "startDate": "29/09/2016",
 "endDate": "24/10/2016",
 “status”: “PENDING”
 "description": "reserve new capacity for billing dept. ",
 "owner": "alan",
 "externalid": "BILLING",
...
{{the updated reservation, as passed in the request payload}}
}
}  
Creating a reservation specifying custom resources for two virtual machines
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/reservations
Sample request
 {
 "name": "Billing Service 2.1",
 "startDate": "29/09/2016",
 "endDate": "24/10/2016",
 "description": "reserve new capacity for billing dept. ",
 "owner": "alan",
 "externalId": "BILLING",
 "priority": "MEDIUM",
 "probability": 100,
 "realizationMode": "MANUAL",
 "resources": {
   "resourceSpecs": [
     {
       "name": "Billing-VM",
       "numItems": 2,
       "enttypenm": "gm",
       "cpuCores": 1,
       "cpuTotalMHz": 2000,
       "memTotal": 4294967296,
       "storageTotal": 5368709120
     }
   ]
 },
 "capacityPools": [
   {
     "capacityPoolLookup": {
       "id": 2172
     }
   }
 ]
}
Sample response
{
 "status": "OK",
"message": "The reservation has been successfully created"
“reservation” : {
{{the updated reservation, as passed in the request payload}}
}
}

Creating a new committed reservation
Information

To create a reservation to commit automatically (Parameter - "status": "REQUEST_COMMIT"), you must specify the placement (Parameter - "reservationTargetLookup").

Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/reservations 
Sample request
{
 "name": "ACME new video streaming platform",
 "startDate": "01/04/2017",
 "description": "The new video streaming platform that will support pay-per-view cartoon movies on mobile devices.",
 "owner": "alan",
 "status": "REQUEST_COMMIT",
 "externalId": "",
 "priority": "HIGH",
 "probability": 100,
 "realizationMode": "AUTOMATIC",
 "highAvailability": "NO",
 "items": [
   {
     "name": "Application Server 2",
     "systemTemplateLookup": {
       "id": 2526
     },
     "reservationTargetLookup": {
       "lookupFields": [
           {"lookupField": "NAME","lookupValue": "vh.pl-pun-bco-dv03"}
       ]
     }
   },
   {
     "name": "Application Server 1",
     "systemTemplateLookup": {
        "lookupFields": [
           {"lookupField": "NAME","lookupValue": "vm.kvm.small"}
       ]
     },
     "reservationTargetLookup": {
       "lookupFields": [
           {"lookupField": "NAME","lookupValue": "vh.pl-pun-bco-dv01"}
       ]
     }
   },
   {
     "name": "File server",
     "systemTemplateLookup": {
       "id": 2527
     },
     "reservationTargetLookup": {
       "lookupFields": [
           {"lookupField": "NAME","lookupValue": "vh.bco-kvm-icehouse"}
       ]
     }
   },
   {
     "name": "Database",
     "systemTemplateLookup": {
        "lookupFields": [
           {"lookupField": "NAME","lookupValue": "vm.kvm.large"}
       ]
     },
     "reservationTargetLookup": {
       "lookupFields": [
           {"lookupField": "NAME","lookupValue": "vh.bco-kvm-icehouse"}
       ]
     }
   }
 ],
 "capacityPools": [
   {
     "capacityPoolLookup": {
       "id": 2180
     }
   }
 ]
} 
Sample response
{
"status": "OK",
"message": "The reservation has been successfully created"
“reservation” : {
{{the updated reservation, as passed in the request payload}}
}
}

Back to Top

Delete an existing reservation

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

DELETE

rsv/reservations/{reservation-id}

Reservation ID

 

Sample request and response files

Deleting a reservation
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/reservations/{{rsv-id}}
Sample response
{
 "status" : "OK",
 "message" : "The reservation has been successfully deleted."
}

Back to Top

Search for a reservation

Search for reservations that match query criteria

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

POST

rsv/search/reservations

filters

 

Sample request and response files

Searching for a reservation
Sample request
{
 "filters" : [ {
   "field" : "name",
   "operator" : "EQUAL",
   "value" : "my_rsv"
 }, {
   "field" : "startDate",
   "operator" : "GREATER_THAN",
   "value" : "12/12/2014"
 }, {
   "field" : "status",
   "operator" : "IN",
   "values" : ["ACCEPTED","PENDING"]
 } ]
}
Sample response
{
 "reservations" : [ {
   "href" : "http://{{TSCO_DH}}:8280/dh-services/rsv/reservations/10034",
   "id" : "10034",
   "name" : "rsv_34"
 }, {
   "href" : "http://{{TSCO_DH}}:8280/dh-services/rsv/reservations/10032",
   "id" : "10032",
   "name" : "my_test_rsv"
 } ]
}

Back to Top

Get details for a reservation item

Retrieve the details of a reservation item.

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

GET

rsv/reservations/{reservation-id}/items/{item-id}
  • Reservation ID
  • Item ID

 

Sample request and response files

The following sample request and response files explain getting details about a reservation item given its id and given the reservation id where the item is used. The request retrieves the details of reservation items. Depending on the reservation configuration, a reservation item can be either a template instance or a custom resource instance and the returned data change accordingly.

Given the reservation item id and the reservation id where item is used, retrieving details about a reservation item
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/reservations/{[reservation-id}}/items/{{item-id}}
Sample response (Template)
{
 "href": "{{TSCO_DH}}:8280/dh-services/rsv/reservations/21834/items/28031",
 "id": 28031,
 "name": "template_kvm",
 "systemTemplate": {
   "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/1859903",
   "id": 1859903,
   "name": "template_kvm"
 }
}
Sample response (Custom resource)
{
 "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/reservations/21834/items/41623",
 "id": 41623,
 "name": "www-0",
 "resourceSpec": {
   "id": 1921176,
   "name": "www",
   "enttypenm": "gm",
   "cpuCores": 1,
   "cpuTotalMHz": 1000,
   "memTotal": 1073741824,
   "storageTotal": 1073741824,
   "cpuEntitledCapacity": 1,
   "cpuUtilization": 1,
   "memUtilization": 1,
   "storageUtilization": 1
 }
}

Back to Top

Update a reservation item

If a reservation target is already specified, you can change it, but you cannot remove it. If a target is not already specified, you cannot specify a new one.

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

PUT

rsv/reservations/{reservation-id}/items/{item-id}
  • Reservation ID
  • Item ID

 

Sample request and response files

Given the reservation id and the item id, updating a reservation item.
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/reservations/{[reservation-id}}/items/{{item-id}}
Sample request (Template)
{
 "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/reservations/21834/items/41626",
 "id": 41626,
 "name": "Medium VMware VM-1",
 "systemTemplate": {
   "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/1603198",
   "id": 1603198,
   "name": "Medium VMware VM"
 }
}
Sample request (Custom resource)
{
 "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/reservations/21834/items/41624",
 "id": 41624,
 "name": "www-1",
 "resourceSpec": {
   "id": 1921176,
   "name": "www",
   "enttypenm": "gm",
   "cpuCores": 1,
   "cpuTotalMHz": 1000,
   "memTotal": 1073741824,
   "storageTotal": 107374182
   "cpuEntitledCapacity": 1,
   "cpuUtilization": 1,
   "memUtilization": 1,
   "storageUtilization": 1
 }
}
Sample response
{
 "status": "OK",
 "message": "The reservation item has been successfully updated",
 "item": {
   {{the updated item, as passed in the request payload}}
 }
}

Back to Top

Delete a reservation item

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

DELETE

rsv/reservations/{reservation-id}/items/{item-id}
  • Reservation ID
  • Item ID

 

Sample request and response files

Given the reservation id and the item id, removing a reservation item from a reservation.
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/reservations/{[reservation-id}}/items/{{item-id}}
Sample response
{
 "status": "OK",
 "message": "The item has been successfully deleted"
}

Back to Top

Offboardings action

Get offboarding details

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

GET

rsv/offboardings/{offboarding-id}

Offboarding ID

 

Sample request and response files

Retrieving offboarding details
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/onboardings/{offboarding-id}
Sample response
{
   "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/offboardings/10232",
   "id": 10232,
   "name": "Offboarding_ESXHost",
   "offboardingDate": "20/01/2015",
   "resourceRequirementSummary": {
       "numSystems": 1,
       "cpuCores": 8,
       "cpuTotalMHz": 18392,
       "memTotal": 68671242240,
       "storageTotal": 2026956128256
   },
   "resources": {
       "resourceTemplates": [
           {
               "numItems": 1,
               "systemTemplate": {
                   "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/2216",
                   "id": 2216,
                   "name": "VMwareHost.medium"
               }
           }
       ]
   },
   "reservationTarget": {
       "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/reservationtargets/2158",
       "id": 2158,
       "name": "Cluster-7"
   }
}

Back to Top

Update an existing offboarding

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

PUT

rsv/offboardings/{offboarding-id}

  • Offboarding ID
  • Name   
  • Offboarding date
  • Reservation resources (resourceTemplates
  • or resourceSpecs)
  • Reservation Target
  • Description
  • Realization Mode

Sample request and response files

Updating an existing offboarding
Sample request
{
   "name": "Offboarding_ESXHost",
   "offboardingDate": "29/01/2015",
   "resources": {
       "resourceTemplates": [
           {
               "numItems": 1,
               "systemTemplateLookup": {
                   "id": "2216"
               }
           }
       ]
   },
   "reservationTarget": {
       "id": 2162
   }
}
Sample response
{
   "status": "OK",
   "message": "The offboarding has been successfully updated",
   "offboarding": {
       "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/offboardings/10232",
       "id": 10232,
       "name": "Offboarding_ESXHost",
        "offboardingDate": "29/01/2015",
       "resourceRequirementSummary": {
           "numSystems": 1,
           "cpuCores": 8,
           "cpuTotalMHz": 18392,
           "memTotal": 68671242240,
           "storageTotal": 2026956128256
       },
       "resources": {
           "resourceTemplates": [
               {
                   "numItems": 1,
                   "systemTemplate": {
                       "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/2216",
                       "id": 2216,
                       "name": "template_pe-pun-bco-dv05"
                   }
               }
           ]
       },
       "reservationTarget": {
           "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/reservationtargets/2162",
           "id": 2162,
           "name": "Cluster-4"
       }
   }
}

Back to Top

Create a new offboarding

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

POST

rsv/offboardings

  • Name   
  • Offboarding date
  • Reservation resources (resourceTemplates
  • or resourceSpecs)
  • Reservation Target
  • Description
  • Realization Mode

Sample request and response files

 

Creating a new offboarding
Sample request
{
   "name": "Offboarding_ESXHost",
   "offboardingDate": "20/01/2015",
   "resources": {
       "resourceTemplates": [
           {
               "numItems": 1,
               "systemTemplateLookup": {
                   "id": "2216"
               }
           }
       ]
   },
   "reservationTarget": {
       "id": 2158
   }
}
Sample response
{
   "status": "OK",
   "message": "The offboarding has been successfully created",
   "offboarding": {
       "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/offboardings/10232",
       "id": 10232,
       "name": "Offboarding_ESXHost",
       "offboardingDate": "20/01/2015",
       "resourceRequirementSummary": {
           "numSystems": 1,
           "cpuCores": 8,
           "cpuTotalMHz": 18392,
           "memTotal": 68671242240,
           "storageTotal": 2026956128256
       },
       "resources": {
           "resourceTemplates": [
               {
                   "numItems": 1,
                   "systemTemplate": {
                       "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/2216",
                       "id": 2216,
                       "name": "VMwareHost.medium"
                   }
               }
           ]
       },
       "reservationTarget": {
           "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/reservationtargets/2158",
           "id": 2158,
           "name": "Cluster-7"
       }
   }
}

Back to Top

Delete an existing offboarding

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

DELETE

rsv/offboardings/{offboarding-id}

Offboarding ID

 

Sample request and response files

 

Deleting an existing offboarding
Sample request URL
 http://{{TSCO_DH}}:8280/dh-services/rsv/onboardings/{offboarding-id}
Sample response
 {
 "status" : "OK",
 "message" : "The offboarding has been successfully deleted."
}

Back to Top

Search for an existing offboarding based on query criteria

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

POST

rsv/search/offboardings

 

  • OffboardingID
  • Name 
  • Status
  • ReservationTarget

Sample request and response files

Searching for an existing offboarding
Sample request
 {
 "filters" : [ {
   "field" : "offboardingDate",
   "operator" : "EQUAL",
   "value" : "12/12/2014"
 } ]
}
Sample response
 {
 "offboardings" : [ {
   "href" : "http://{{TSCO_DH}}:8280/dh-services/rsv/onboardings/459",
   "id" : "459",
   "name" : "my_test_offboarding"
 } ]
}

Back to Top

Onboardings action

Get details for an onboarding

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

GET

rsv/onboardings/{onboarding-id}

Onboarding ID

 

Sample request and response files

Retrieving onboarding data
Sample request URL
 http://{{TSCO_DH}}:8280/dh-services/rsv/onboardings/{onboarding-id}
Sample response
 {
   "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/onboardings/10231",
   "id": 10231,
   "name": "Onboarding_NewHost",
   "description": "Onboarding new ESX hosts",
   "onboardingDate": "16/01/2015",
   "offboardingDate": "16/02/2015",
   "resourceRequirementSummary": {
       "numSystems": 2,
       "cpuCores": 16,
       "cpuTotalMHz": 36784,
       "memTotal": 137342484480,
       "storageTotal": 4053912256512
   },
   "resources": {
       "resourceTemplates": [
           {
               "numItems": 1,
               "systemTemplate": {
                   "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/2216",
                   "id": 2216,
                   "name": "template_{{TSCO_DH}}"
               }
           }
       ]
   },
   "reservationTarget": {
       "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/reservationtargets/2162",
       "id": 2162,
       "name": "Cluster-4"
   }
}

Back to Top

Update an existing onboarding

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

PUT

rsv/onboardings/{onboarding-id}
  • Onboarding ID
  • Name  
  • Onboarding date  
  • Template (resourceTemplates
    or resourceSpecs)
  • Reservation Target or
    Capacity Pool (Onboarding on
    hypothetical Reservation Target)
  • Description 
  • Offboarding date
  • Realization Mode

Sample request and response files

Updating an existing onboarding
Sample request
{
 "href": "http://{{TSCO_DH}}/dh-services/rsv/onboardings/{onboarding-id}",
 "id": 16067,
 "name": "testOnboarding_POST_OnCapacityContainer",
 "onboardingDate": "24/10/2016",
 "status": "COMMITTED",
 "realizationMode": "AUTOMATIC",
 "resourceRequirementSummary": {
   "numSystems": 4
 },
 "resources": {
   "resourceTemplates": [
     {
       "numItems": 4,
       "systemTemplate": {
         "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/4019",
         "id": 4019,
         "name": "VMware"
       }
     }
   ]
 },
 "reservationTarget": {
   "href": "http://{{TSCO_DH}}/dh-services/rsv/reservationtargets/1390874",
   "id": 1390874,
   "name": "CE-TestCluster"
 }
}

Sample response
{
 "status": "OK",
 "message": "The onboarding has been successfully updated",
 "onboarding": {
<<the updated onboarding item>>
 }
}

Back to Top

Create a new onboarding

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

POST

rsv/onboardings
  • Name  
  • Onboarding date  
  • Reservation resources (resourceTemplates
    or resourceSpecs)
  • Reservation Target OR Capacity Pool (Onboarding on
    hypothetical Reservation Target)
  • Description 
  • Offboarding date
  • Realization Mode

Sample request and response files

Adding a new host to a VMware Cluster
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/onboardings
Sample request
{
 "name": " Onboarding_NewHost ",
 "description": "Onboarding new ESX hosts",
 "onboardingDate": "25/10/2016",
 "realizationMode": "AUTOMATIC",
 "resources": {
   "resourceTemplates": [
     {
       "numItems": 1,
       "systemTemplateLookup": {
         "id": 2184
       }
     }
   ]
 },
 "reservationTargetLookup": {
   "id": 3635
 }
}
Sample response
{
   "status": "OK",
   "message": "The onboarding has been successfully created",
   "onboarding": {
       "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/onboardings/10229",
       "id": 10229,
       "name": "Onboarding_NewHost",
       "description": "Onboarding new ESX hosts",
       "onboardingDate": "25/10/2016",
       "resourceRequirementSummary": {
           "numSystems": 3,
           "cpuCores": 24,
           "cpuTotalMHz": 55176,
           "memTotal": 206013726720,
           "storageTotal": 6080868384768
       },
       "resources": {
           "resourceTemplates": [
               {
                   "numItems": 1,
                   "systemTemplate": {
                       "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/2184",
                       "id": 2184,
                       "name": "VMwareHost.medium"
                   }
               }
           ]
       },
       "reservationTarget": {
           "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/reservationtargets/3635",
           "id": 3635,
           "name": "Cluster-4"
       }
   }
}
Adding two new VMware hosts to a VMware hosts capacity pool
Sample request URL
 http://{{TSCO_DH}}:8280/dh-services/rsv/onboardings
Sample request
{
 "name": "New hosts",
 "description": "new host assigned to Milan R&D capacity pool",
 "onboardingDate": "28/10/2016",
 "status": "COMMITTED",
 "realizationMode": "AUTOMATIC",
 "resources": {
   "resourceTemplates": [
     {
       "numItems": 2,
       "systemTemplateLookup": {
         "id": 3154
       }
     }
   ]
 },
 "capacityPool": {
   "id": 3155
 }
}
Sample response
{
 "status": "OK",
"message": "The onboarding has been successfully created"
“onboarding” : {
{{the updated onboarding, as passed in the request payload}}
}
}

Back to Top

Delete an existing onboarding

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

DELETE

rsv/onboardings/{onboarding-id}

Onboarding ID

 

 

Sample request and response files

Deleting an onboarding
Sample request URL
 http://{{TSCO_DH}}:8280/dh-services/rsv/onboardings/{onboarding-id}
Sample response
 {
 "status" : "OK",
 "message" : "The onboarding has been successfully deleted."
}

Back to Top

Search for an existing onboarding based on query criteria

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

POST

rsv/search/onboardings

 

  • OnboardingID
  • Name
  • Status
  • ReservationTarget

 

Sample request and response files

Searching for an existing onboarding
Sample request
 {
 "filters" : [ {
   "field" : "name",
   "operator" : "LIKE",
   "value" : "test_onboarding"
 }, {
   "field" : "status",
   "operator" : "IN",
   "values" :["COMMITTED","PENDING"]
 } ]
}
Sample response
 {
 "onboardings" : [ {
   "href" : "http://{{TSCO_DH}}:8280/dh-services/rsv/onboardings/34",
   "id" : "34",
   "name" : "my_test_onboarding"
 }, {
   "href" : "http://{{TSCO_DH}}:8280/dh-services/rsv/onboardings/553",
   "id" : "553",
   "name" : "onboardingDec"
 } ]
}

Back to Top

Reservation targets action

Get details for a Reservation Target

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

GET

rsv/reservationTargets/{container-id}

Reservation Target ID

 

Sample request and response files

Given an existing Reservation Target id, retrieve list of reservations to this target
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/reservationtargets/{{reservation-target-id}}
Sample response
{
"href": "http://{{TSCO_DH}}:8280/dh-services/rsv/reservationtargets/1871638",
 "id": 1871638,
 "name": "Hypothetical Capacity Container - test-vmw",
 "alertstatus": [],
 "description": "This is an hypothetical container representing an onboarding event to a container pool",
 "enttypenm": "hh:vmw",
 "hypothetical": true,
 "capacityPools": [
   {
     "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/capacitypools/1857151",
     "id": 1857151,
     "name": "test-vmw"
   }
 ],
 "reservations": [],
 "onboardings": [],
 "offboardings": []
}

Back to Top

Search for a Reservation Target that matches the query criteria

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

POST

rsv/search/reservationtargets

filters

 

Sample request and response files

Searching for reservation targets
Sample request
 {
 "filters" : [ {
   "field" : "name",
   "operator" : "LIKE",
   "value" : "CLM%"
 }, {
   "field" : "capacitypoolids",
   "operator" : "IN",
   "values" : ["386","444"]
 } ]
}
Sample response
 {
 "reservationTargets" : [ {
   "href" : "http://{{TSCO_DH}}:8280/dh-services/rsv/reservationtargets/442",
   "id" : "442",
   "name" : "CLM-Cluster"
 } ]
}

Back to Top

Capacity pools action

Get data for an existing capacity pool

HTTP method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

GET

rsv/capacitypools/{pool-id}

Capacity Pool ID

 

Sample request and response files

Given an existing capacity pool id, retrieve list of reservations for the capacity pool
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/capacitypools/{{capacity-pool-id}}
Sample response
{
 "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/capacitypools/1857153",
 "id": 1857153,
 "name": "vmw-cpool",
 "alertstatus": [],
 "enttypenm": "cp:vmwh",
 "technology": "VMWARE",
 "location": "UNKNOWN",
 "reservations": [
   {
     "href": "https://{{TSCO_DH}}:8280/dh-services/rsv/reservations/10285",
     "id": 10285,
     "name": "test-cpool"
   }
 ]
}

Back to Top

Search for capacity pools that match query criteria

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

POST

rsv/search/capacitypools

 

  • Name
  • Technology
  • Tags

Sample request and response files

Searching for capacity pools
Sample request
{
 "filters" : [ {
   "field" : "name",
   "operator" : "LIKE",
   "value" : "Milan%"
 }, {
   "field" : "technology",
   "operator" : "EQUAL",
   "value" : "VMware"
 } ]
}
Sample response
 {
 "capacityPools" : [ {
   "href" : "http://{{TSCO_DH}}:8280/dh-services/rsv/capacitypools/386",
   "id" : "386",
   "name" : "Milan capacity pool"
 } ]
}

Back to Top

Tenants action

Get tenant details and alert status information

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

GET

rsv/tenants/{tenant-id}

Tenant ID

 

Sample request and response files

Given a tenant id, retrieve quota for this tenant
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/tenants/{{tenant-id}}
Sample response
{
 "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/tenants/1889779",
 "id": 1889779,
 "name": "delten2",
 "alertstatus": [],
 "tenantQuota": {
   "numItems": 2,
   "cpuCores": 2,
   "cpuTotalMhz": 2000,
   "memTotal": 2147483648,
   "storageTotal": 2147483648
 }
}

Back to Top

Search for tenants based on query criteria

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

POST

rsv/search/tenants

 

  • ID
  • Name
  • Description
  • Status

Sample request and response files

Searching for tenants
Sample request
{
 "filters" : [ {
   "field" : "name",
   "operator" : "EQUAL",
   "value" : "Development"
 } ]
}
Sample response
{
 "tenants" : [ {
   "href" : "http://{{TSCO_DH}}:8280/dh-services/rsv/tenants/1864874",
   "id" : 1864874,
   "name" : "Development"
   "alert_status": [],
} ]
}

Back to Top

System templates action

Get details about a system template

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

GET

rsv/systemtemplates/{template-id}

Template ID

 

Sample request and response files

Given the template id, retrieving details about a system template.
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/{{template-id}}
Sample response
{
   "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/{{template-id}}",
   "id": 1921284,
   "name": "Billing VM1",
   "enttypenm": "gm:vmw",
   "resourceSpec": {
     "cpuCores": 8,
     "cpuTotalMHz": 20000,
     "memTotal": 2147483648,
     "storageTotal": 64424509440,
     "cpuUtilization": 1,
     "memUtilization": 1,
     "storageUtilization": 1
   }
}

Back to Top

Update a system template

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

PUT

rsv/systemtemplates/{template-id}

Template ID

  • Name
  • Description
  • Metric Name and Value

Sample request and response files

Updating a system template
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/{{template-id}}
Sample request
{
 "name": "Billing VM",
 "enttypenm": "gm:vmw",
 "tags": [
   {
     "tag": "Oracle11g",
     "typeId": 10003,
     "type": "Database Licenses"
   }
 ],
 "resourceSpec": {
   "cpuCores": 10,
   "cpuTotalMHz": 20000,
   "memTotal": 2147483648,
   "storageTotal": 64424509440,
   "os": "LINUX",
   "cpuUtilization": 0.1,
   "memUtilization": 0.9,
   "storageUtilization": 0.4
 }
} 
Sample response
{
 "status": "OK",
 "message": "The system template Billing VM[sysid:1921326] has been successfully updated",
 "systemtemplate": {
   {{the updated item, as passed in the request payload}}
 }
}

Back to Top

Create a new system template

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

POST

rsv/systemtemplates

  • Name
  • System Type
  • Metric Name and Value
  • Min required from reservations
    (VCPU_NUM, REAL_MEM,DISK)
  • Description
  • Metric Name and Value

Sample request and response files

Creating a new system template
Sample request URL
http:// {{TSCO_DH}}:8280/dh-services/rsv/systemtemplates
Sample request
{
 "name": "Billing VM1",
 "enttypenm": "gm:vmw",
 "resourceSpec": {
   "cpuCores": 8,
   "cpuTotalMHz": 20000,
   "memTotal": 2147483648,
   "storageTotal": 64424509440
 }
}
Sample response
{
 "status": "OK",
 "message": "The system template Billing VM1 has been successfully created with sysid: 1921284",
 "systemtemplate": {
   "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/1921284",
   "id": 1921284,
   "name": "Billing VM1",
   "enttypenm": "gm:vmw",
   "resourceSpec": {
     "cpuCores": 8,
     "cpuTotalMHz": 20000,
     "memTotal": 2147483648,
     "storageTotal": 64424509440,
     "cpuUtilization": 1,
     "memUtilization": 1,
     "storageUtilization": 1
   }
 }
}

Back to Top

Delete a system template

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

DELETE

rsv/systemtemplates/{template-id}

Template ID

 

Sample request and response files

Given the template id, deleting a system template.
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/{{template-id}}
Sample response
 {
 "status" : "OK",
 "message" : "The system template has been successfully deleted.",
}

Back to Top

Search for system template based on query criteria

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

POST

rsv/search/systemtemplates

 

  • ID
  • Name 
  • SystemType
  • Lookupname
  • SystemType
  • ResourceSpec values for: cpuCores, cpuEntitledCapacity,
    cputTotalMHz, memTotal, storageTotal

Sample request and response files

Searching for system template based on query criteria
Sample request
 {
 "filters" : [ {
   "field" : "name",
   "operator" : "EQUAL",
   "value" : "sys_template"
 }, {
   "field" : "enttypenm",
   "operator" : "EQUAL",
   "value" : "gm:vmw"
 }, {
   "field": "lookupName",
   "operator": "EQUAL",
   "value" : "sys_templ_lk_1234"
 }]
}
Sample response
 {
 "systemTemplates" : [ {
   "href" : "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/566",
   "id" : "566",
   "name" : "template_vm-aus-bco-dv56"
 }, {
   "href" : "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/78",
   "id" : "78",
   "name" : "template_{{TSCO_DH}}"
 } ]
}

Back to Top

Service templates action

Get details about a service template

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

GET

rsv/servicetemplates/{template-id}

Template ID

 

Sample request and response files

Given the template id, retrieving details about a service template.
Sample request URL
http://{{TSCO_DH}}:8280/dh-services/rsv/servicetemplates/{{template-id}}
Sample response
{
 "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/servicetemplates/1604397",
 "id": 1604397,
 "name": "Mail Service",
 "resourceRequirementSummary": {
   "cpuCores": 1
 },
 "systemTemplates": [
   {
     "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/1604400",
     "id": 1604400,
     "name": "template_VFW-Primary"
   },
   {
     "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/1604399",
     "id": 1604399,
     "name": "template_asi-citrix1-VLB-Secondary"
   },
   {
     "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/1604398",
     "id": 1604398,
     "name": "template_ASA-updated-VFW-Secondary"
   }
 ]
}

Back to Top

Search for service template based on query criteria

Method

URI pattern

Required
Request
Parameters

Optional Request

Parameters

POST

rsv/search/servicetemplates

 

  • ID
  • Name

Sample request and response files

Searching for service template
Sample request
 {
   "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/servicetemplates/2221",
   "id": 2221,
   "name": "service_template",
   "resourceRequirementSummary": {
       "vcpuNum": 6,
       "cpuCores": 6,
       "cpuTotalMHz": 13642,
       "memTotal": 17179869184,
       "storageTotal": 123054081643
   },
   "systemTemplates": [
       {
           "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/2214",
           "id": 2214,
           "name": "VMware.medium"
       },
       {
           "href": "http://{{TSCO_DH}}:8280/dh-services/rsv/systemtemplates/2213",
           "id": 2213,
           "name": "VMware.small"
       }
   ]
}
Sample response
 {
 "serviceTemplates" : [ {
   "href" : "http://{{TSCO_DH}}:8280/dh-services/rsv/servicetemplates/234",
   "id" : "234",
   "name" : "BCOService"
 }, {
   "href" : "http://{{TSCO_DH}}:8280/dh-services/rsv/servicetemplates/544",
   "id" : "544",
   "name" : "CLMService"
 } ]
}

Back to Top

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*