Introduction to the Zerto Virtual Replication Restful APIs : Managing VPGs : A First Time Tutorial Using the vpgSettings API
  
A First Time Tutorial Using the vpgSettings API
This walk-through uses the URLs that are passed to create a session and then edit an existing VPG. The examples were tested using a REST client, such as Postman, used in Google Chrome, and available from http://www.getpostman.com/.
In all the example code, the zvm_ip is the IP of the Zerto Virtual Manager where the API will run and both the content type and accept type is application/json.
To start a session:
Use the following URL with a POST method and basic authentication to access the hypervisor management tool, vCenter Server or the Microsoft SCVMM.
https://zvm_ip:9669/v1/session/add
The Response Header that is returned is similar to the following:
Content-Length: 0
Date: Mon, 29 Jun 2015 08:50:58 GMT
Server: Microsoft-HTTPAPI/2.0
x-zerto-session: 9UDQD6RG7YF33QJLWQXGJV8C453N277NA22P7FSNWVZCJTWCBRHQ
The fourth line contains the value of x-zerto-session, which is used in all subsequent calls.
To create a VPG:
1. Create a skeleton VPG settings object, using the following URL with a POST method:
https://zvm_ip:9669/v1/vpgsettings
and the following request body:
{}
The API must be run on the protected site.
The vpgSettingsIdentifier is returned.
2. Get the skeleton structure for the VPG settings object using the following URL with a GET method:
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677
Where 3864850e-1580-4518-95d1-f88a4d97c677 is the vpgSettingsIdentifier returned in step 1.
3. Set in the basic parameters as required, at least the following fields:
JournalHistoryInHours
Name
Priority
ProtectedSiteIdentifier
RecoverySiteIdentifier
RpoInSeconds
TestIntervalInMinutes.
Get the RecoverySiteIdentifier by running the virtualizationsites API, using the following URL with the GET method:
https://zvm_ip:9669/v1/virtualizationsites
Note: If required, the ServiceProfileIdentifier can be retrieved using the /v1/serviceprofiles API with the GET method and the ZorgIdentifier can be retrieved using the /v1/zorgs API with the GET method.
4. Get the structures for the Journal, Networks and Recovery sections in the skeleton by copying the Json request bodies from the examples in the help, accessed by running the following URL:
https://zvm_ip:9669/v1/vpgsettings/help
For more details, refer to Getting Help for an API.
5. Use the virtualizationsites API to get the following values from the recovery site to add to the skeleton settings:
DatastoreIdentifier for both the journal and recovery storage
DefaultNetworkIdentifier, for both the failover and move network and for the test failover network
DefaultFolderIdentifier
DefaultHostClusterIdentifier or DefaultHostIdentifier or ResourcePoolIdentifier
6. Set the journal limitations as required. A zero, 0, value means unlimited.
7. Get the identifiers for the virtual machines that are not protected, with the virtualizationsites/vms API and add the list of virtual machines you want protected in the VPG, as in the following example
[{"VmIdentifier": "13d550a4-24af-4914-9ca4-09f8619eb703.vm-147"}]
8. Remove the vpgIdentifier and vpgSettingsIdentifier lines from the skeleton.
9. Create a new VPG settings object by using the following URL with the POST method:
https://zvm_ip:9669/v1/vpgsettings
and the updated skeleton for the request body.
10. Create the VPG by committing the updated skeleton, using the following URL with a POST method:
https://zvm_ip:9669/v1/vpgsettings/a965180f-1375-6545-9d21-556a4a41c871/commit
The task identifier is returned which can then be used with the /v1/tasks/{taskIdentifier} API to monitor the task progress. The settings object for this VPG is also destroyed.
Note: For details about using virtualizationsites APIs, refer to “Virtualization Sites API”, on page 78.
The following is an example VPG settings object skeleton after it has been edited:
{
  "Backup": null,
  "Basic": {
    "JournalHistoryInHours": 4,
    "Name": "MyFirstVpg",
    "Priority": "Medium",
    "ProtectedSiteIdentifier": "6c36720e-b32d-44de-9600-042ce5268d0d",
    "RecoverySiteIdentifier": "02159615-16d8-40e0-87f8-2fe669bf414f",
    "RpoInSeconds": 300,
    "ServiceProfileIdentifier": null,
    "TestIntervalInMinutes": 262080,
    "UseWanCompression": true,
    "ZorgIdentifier": null
  },
  "BootGroups": {
    "BootGroups": [
      {
        "BootDelayInSeconds": 0,
        "BootGroupIdentifier": "00000000-0000-0000-0000-000000000000",
        "Name": "Default"
      }
    ]
  },
  "Journal": {
    "DatastoreIdentifier":"841c3a57-e4bb-4e53-b045-47e95da4ece9.datastore-201",
    "Limitation":{
      "HardLimitInMB":0,
      "HardLimitInPercent":0,
      "WarningThresholdInMB":0,
      "WarningThresholdInPercent":0
    }
  },
  "Networks": {
    "Failover":{
      "Hypervisor":{
        "DefaultNetworkIdentifier":"841c3a57-e4bb-4e53-b045-47e95da4ece9.network-34"
      }
    },
    "FailoverTest":{
      "Hypervisor":{
        "DefaultNetworkIdentifier":"841c3a57-e4bb-4e53-b045-47e95da4ece9.network-34"
      }
    }
  },
  "Recovery": {
    "DefaultDatastoreIdentifier":"841c3a57-e4bb-4e53-b045-47e95da4ece9.datastore-201",
    "DefaultFolderIdentifier":"841c3a57-e4bb-4e53-b045-47e95da4ece9.group-v22",
    "DefaultHostClusterIdentifier":null,
    "DefaultHostIdentifier":"841c3a57-e4bb-4e53-b045-47e95da4ece9.host-30",
    "ResourcePoolIdentifier":null
  },
  "Scripting": {
    "PostBackup": null,
    "PostRecovery": {
      "Command": null,
      "Parameters": null,
      "TimeoutInSeconds": 0
    },
    "PreRecovery": {
      "Command": null,
      "Parameters": null,
      "TimeoutInSeconds": 0
    }
  },
  "Vms": [{"VmIdentifier": "13d550a4-24af-4914-9ca4-09f8619eb703.vm-147"}]
}
 
To update an existing VPG:
1. Use the following URL with a GET method and the x-zerto-session added to the header to retrieve the VPG identifiers for existing VPGs. A VPG identifier is then used to create the VPG settings object:
https://zvm_ip:9669/v1/vpgs
The response to this command is a list of VPGs with information about each VPG.
2. Copy the relevant VpgIdentifier from the response to use in the request body of another API, and create a VPG settings object for this VPG. The request body contains code similar to the following:
{
  "VpgIdentifier":"b030cbc3-3cd1-4a3b-9378-afd2a6e0ee88"
}
Note: The content type for this example is application/json.
Use the following URL with a POST method to create the VPG settings object for the VPG:
https://zvm_ip:9669/v1/vpgsettings
The response to this command is the vpgSettingsIdentifier and the VPG settings object is created.
3. Get the VPG settings object for review, using the following URL with a GET method:
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677
Where 3864850e-1580-4518-95d1-f88a4d97c677 is the vpgSettingsIdentifier returned in step 2.
4. Updating the VPG is done using the following steps:
a) Get the current settings for the part of the VPG you want to update. For example, to update the basic values, use the following URL with a GET method:
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677/basic
Where 3864850e-1580-4518-95d1-f88a4d97c677 is the vpgSettingsIdentifier returned in step 2.
The following example response body is returned:
{
  "JournalHistoryInHours": 4,
  "Name": "Test-Using-API",
  "Priority": "Medium",
  "ProtectedSiteIdentifier": "6c36720e-b32d-44de-9600-042ce5268d0d",
  "RecoverySiteIdentifier": "02159615-16d8-40e0-87f8-2fe669bf414f",
  "RpoInSeconds": 540,
  "ServiceProfileIdentifier": null,
  "TestIntervalInMinutes": 131040,
  "UseWanCompression": true,
  "ZorgIdentifier": null
}
b) Use the response body from step 4 to create the request body for the update with the required changes and then use this request body with the following URL with a PUT method:
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677/basic
The following example request body changes the priority, journal history and compression settings for the VPG:
{
  "JournalHistoryInHours": 10,
  "Priority": "High",
  "UseWanCompression": false,
}
c) You can verify that the VPG settings object has been updated by rerunning the following URL with a GET method:
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677/basic
d) Update the VPG with these new settings by committing the change, using the following URL with a POST method:
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677/commit
The task identifier is returned which can then be used with the /v1/tasks/{taskIdentifier} API to monitor the task progress. The settings object for this VPG is also destroyed.
For details of the /v1/tasks API, refer to the Zerto Virtual Replication RESTful API Reference Guide documentation.
To add a virtual machine to the VPG:
1. Get the identifier for the protected site, for the virtual machines that are not protected, with the /v1/virtualizationsites or /v1/localsite API. For example, using the following URL with a GET method:
https://zvm_ip:9669/v1/localsite
The API must be run on the protected site.
2. Get the identifiers for the virtual machines that are not protected, with the /v1/virtualizationsites/vms API, using the following URL with a GET method:
https://zvm_ip:9669/v1/virtualizationsites/6c36720e-b32d-44de-9600-042ce5268d0d/vms
Where 6c36720e-b32d-44de-9600-042ce5268d0d is the local site identifier, returned in step 1. The following example response body is returned:
[
  {
    "VmIdentifier": "13d550a4-24af-4914-9ca4-09f8619eb703.vm-147",
    "VmName": "Operations"
  },
  {
    "VmIdentifier": "13d550a4-24af-4914-9ca4-09f8619eb703.vm-148",
    "VmName": "HR"
  }
]
3. Updating the VPG to include the virtual machine you want to add, by first creating the VPG settings object as described in steps 1 to 3 in To update an existing VPG:, above and then using the following URL with a POST method:
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677/vms
Where 3864850e-1580-4518-95d1-f88a4d97c677 is the vpgSettingsIdentifier. The Request Body contains the following:
{
  "VmIdentifier":"13d550a4-24af-4914-9ca4-09f8619eb703.vm-147"
}
Where 13d550a4-24af-4914-9ca4-09f8619eb703.vm-147 is the virtual machine identifier to add to the VPG.
4. Update the VPG with the virtual machine by committing the change, using the following URL with a POST method:
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677/commit
The task identifier is returned which can then be used with the /v1/tasks/{taskIdentifier} API to monitor the task progress. The settings object for this VPG is also destroyed.