From be571663b2c2ed738a2bab15ae45dabccd865e6a Mon Sep 17 00:00:00 2001 From: Radhika PC Date: Thu, 4 Oct 2012 11:51:03 +0530 Subject: [PATCH] Changed and new API commands documentation --- docs/en-US/added-API-commands.xml | 487 ++++++++++++------ .../change-to-behavior-of-list-commands.xml | 184 ++++--- docs/en-US/changed-apicommands-4.0.xml | 268 ++++++++++ 3 files changed, 697 insertions(+), 242 deletions(-) create mode 100644 docs/en-US/changed-apicommands-4.0.xml diff --git a/docs/en-US/added-API-commands.xml b/docs/en-US/added-API-commands.xml index b63895e7973..237c524b75f 100644 --- a/docs/en-US/added-API-commands.xml +++ b/docs/en-US/added-API-commands.xml @@ -3,165 +3,332 @@ %BOOK_ENTITIES; ]> - - - -
- Added API commands - Added in 3.0.3: - - enableCiscoNexusVSM (Enables Nexus 1000v dvSwitch in &PRODUCT;.) - disableCiscoNexusVSM (Disables Nexus 1000v dvSwitch in &PRODUCT;.) - deleteCiscoNexusVSM (Deletes Nexus 1000v dvSwitch in &PRODUCT;.) - listCiscoNexusVSMs (Lists the control VLAN ID, packet VLAN ID, and data VLAN ID, as well as the IP address of the Nexus 1000v dvSwitch.) - - Added in 3.0.2: - - changeServiceForSystemVm - Changes the service offering for a system VM (console proxy or secondary storage). The system VM must be in a "Stopped" state for this command to take effect. - - - Added in 3.0.1: - - changeServiceForSystemVm - Changes the service offering for a system VM (console proxy or secondary storage). The system VM must be in a "Stopped" state for this command to take effect. - - - Added in 3.0.0: - - - - - - - - assignVirtualMachine (Move a user VM to another user under same domain.) - restoreVirtualMachine (Restore a VM to original template or specific snapshot) - createLBStickinessPolicy (Creates a Load Balancer stickiness policy ) - - - deleteLBStickinessPolicy (Deletes a LB stickiness policy.) - listLBStickinessPolicies (Lists LBStickiness policies.) - ldapConfig (Configure the LDAP context for this site.) - - - addSwift (Adds Swift.) - listSwifts (List Swift.) - migrateVolume (Migrate volume) - - - updateStoragePool (Updates a storage pool.) - authorizeSecurityGroupEgress (Authorizes a particular egress rule for this security group) - revokeSecurityGroupEgress (Deletes a particular egress rule from this security group) - - - createNetworkOffering (Creates a network offering.) - deleteNetworkOffering (Deletes a network offering.) - createProject (Creates a project) - - - deleteProject (Deletes a project) - updateProject (Updates a project) - activateProject (Activates a project) - - - suspendProject (Suspends a project) - listProjects (Lists projects and provides detailed information for listed projects) - addAccountToProject (Adds acoount to a project) - - - deleteAccountFromProject (Deletes account from the project) - listProjectAccounts (Lists project's accounts) - listProjectInvitations (Lists an account's invitations to join projects) - - - updateProjectInvitation (Accepts or declines project invitation) - deleteProjectInvitation (Deletes a project invitation) - updateHypervisorCapabilities (Updates a hypervisor capabilities.) - - - listHypervisorCapabilities (Lists all hypervisor capabilities.) - createPhysicalNetwork (Creates a physical network) - deletePhysicalNetwork (Deletes a Physical Network.) - - - listPhysicalNetworks (Lists physical networks) - updatePhysicalNetwork (Updates a physical network) - listSupportedNetworkServices (Lists all network services provided by &PRODUCT; or for the given Provider.) - - - addNetworkServiceProvider (Adds a network serviceProvider to a physical network) - deleteNetworkServiceProvider (Deletes a Network Service Provider.) - listNetworkServiceProviders (Lists network serviceproviders for a given physical network.) - - - updateNetworkServiceProvider (Updates a network serviceProvider of a physical network) - addTrafficType (Adds traffic type to a physical network) - deleteTrafficType (Deletes traffic type of a physical network) - - - listTrafficTypes (Lists traffic types of a given physical network.) - updateTrafficType (Updates traffic type of a physical network) - listTrafficTypeImplementors (Lists implementors of implementor of a network traffic type or implementors of all network traffic types) - - - createStorageNetworkIpRange (Creates a Storage network IP range.) - deleteStorageNetworkIpRange (Deletes a storage network IP Range.) - listStorageNetworkIpRange (List a storage network IP range.) - - - updateStorageNetworkIpRange (Update a Storage network IP range, only allowed when no IPs in this range have been allocated.) - listUsageTypes (List Usage Types) - addF5LoadBalancer (Adds a F5 BigIP load balancer device) - - - configureF5LoadBalancer (configures a F5 load balancer device) - deleteF5LoadBalancer ( delete a F5 load balancer device) - listF5LoadBalancers (lists F5 load balancer devices) - - - listF5LoadBalancerNetworks (lists network that are using a F5 load balancer device) - addSrxFirewall (Adds a SRX firewall device) - deleteSrxFirewall ( delete a SRX firewall device) - - - listSrxFirewalls (lists SRX firewall devices in a physical network) - listSrxFirewallNetworks (lists network that are using SRX firewall device) - addNetscalerLoadBalancer (Adds a netscaler load balancer device) - - - deleteNetscalerLoadBalancer ( delete a netscaler load balancer device) - configureNetscalerLoadBalancer (configures a netscaler load balancer device) - listNetscalerLoadBalancers (lists netscaler load balancer devices) - - - listNetscalerLoadBalancerNetworks (lists network that are using a netscaler load balancer device) - createVirtualRouterElement (Create a virtual router element.) - configureVirtualRouterElement (Configures a virtual router element.) - - - listVirtualRouterElements (Lists all available virtual router elements.) - - - - - - -
+
+ Added API commands + Added in 4.0 + + + createCounter (Adds metric counter) + + + deleteCounter (Deletes a counter) + + + listCounters (List the counters) + + + createCondition (Creates a condition) + + + deleteCondition (Removes a condition) + + + listConditions (List Conditions for the specific user) + + + createTags. Add tags to one or more resources. Example: + command=createTags +&resourceIds=1,10,12 +&resourceType=userVm +&tags[0].key=region +&tags[0].value=canada +&tags[1].key=city +&tags[1].value=Toronto + + + deleteTags. Remove tags from one or more resources. Example: + command=deleteTags +&resourceIds=1,12 +&resourceType=Snapshot +&tags[0].key=city + + + listTags (Show currently defined resource tags) + + + createVPC (Creates a VPC) + + + listVPCs (Lists VPCs) + + + deleteVPC (Deletes a VPC) + + + updateVPC (Updates a VPC) + + + restartVPC (Restarts a VPC) + + + createVPCOffering (Creates VPC offering) + + + updateVPCOffering (Updates VPC offering) + + + deleteVPCOffering (Deletes VPC offering) + + + listVPCOfferings (Lists VPC offerings) + + + createPrivateGateway (Creates a private gateway) + + + listPrivateGateways (List private gateways) + + + deletePrivateGateway (Deletes a Private gateway) + + + createNetworkACL (Creates a ACL rule the given network (the network has to belong to + VPC)) + + + deleteNetworkACL (Deletes a Network ACL) + + + listNetworkACLs (Lists all network ACLs) + + + createStaticRoute (Creates a static route) + + + deleteStaticRoute (Deletes a static route) + + + listStaticRoutes (Lists all static routes) + + + createVpnCustomerGateway (Creates site to site vpn customer gateway) + + + createVpnGateway (Creates site to site vpn local gateway) + + + createVpnConnection (Create site to site vpn connection) + + + deleteVpnCustomerGateway (Delete site to site vpn customer gateway) + + + deleteVpnGateway (Delete site to site vpn gateway) + + + deleteVpnConnection (Delete site to site vpn connection) + + + updateVpnCustomerGateway (Update site to site vpn customer gateway) + + + resetVpnConnection (Reset site to site vpn connection) + + + listVpnCustomerGateways (Lists site to site vpn customer gateways) + + + listVpnGateways (Lists site 2 site vpn gateways) + + + listVpnConnections (Lists site to site vpn connection gateways) + + + Added in 3.0.3: + + + enableCiscoNexusVSM (Enables Nexus 1000v dvSwitch in &PRODUCT;.) + + + disableCiscoNexusVSM (Disables Nexus 1000v dvSwitch in &PRODUCT;.) + + + deleteCiscoNexusVSM (Deletes Nexus 1000v dvSwitch in &PRODUCT;.) + + + listCiscoNexusVSMs (Lists the control VLAN ID, packet VLAN ID, and data VLAN ID, as well + as the IP address of the Nexus 1000v dvSwitch.) + + + Added in 3.0.2: + + + changeServiceForSystemVm + Changes the service offering for a system VM (console proxy or secondary storage). The + system VM must be in a "Stopped" state for this command to take effect. + + + Added in 3.0.1: + + + changeServiceForSystemVm + Changes the service offering for a system VM (console proxy or secondary storage). The + system VM must be in a "Stopped" state for this command to take effect. + + + Added in 3.0.0: + + + + + + + + assignVirtualMachine (Move a user VM to another user under same + domain.) + restoreVirtualMachine (Restore a VM to original template or specific + snapshot) + createLBStickinessPolicy (Creates a Load Balancer stickiness policy + ) + + + deleteLBStickinessPolicy (Deletes a LB stickiness policy.) + listLBStickinessPolicies (Lists LBStickiness policies.) + ldapConfig (Configure the LDAP context for this site.) + + + addSwift (Adds Swift.) + listSwifts (List Swift.) + migrateVolume (Migrate volume) + + + updateStoragePool (Updates a storage pool.) + authorizeSecurityGroupEgress (Authorizes a particular egress rule for this + security group) + revokeSecurityGroupEgress (Deletes a particular egress rule from this + security group) + + + createNetworkOffering (Creates a network offering.) + deleteNetworkOffering (Deletes a network offering.) + createProject (Creates a project) + + + deleteProject (Deletes a project) + updateProject (Updates a project) + activateProject (Activates a project) + + + suspendProject (Suspends a project) + listProjects (Lists projects and provides detailed information for listed + projects) + addAccountToProject (Adds acoount to a project) + + + deleteAccountFromProject (Deletes account from the project) + listProjectAccounts (Lists project's accounts) + listProjectInvitations (Lists an account's invitations to join + projects) + + + updateProjectInvitation (Accepts or declines project + invitation) + deleteProjectInvitation (Deletes a project invitation) + updateHypervisorCapabilities (Updates a hypervisor + capabilities.) + + + listHypervisorCapabilities (Lists all hypervisor + capabilities.) + createPhysicalNetwork (Creates a physical network) + deletePhysicalNetwork (Deletes a Physical Network.) + + + listPhysicalNetworks (Lists physical networks) + updatePhysicalNetwork (Updates a physical network) + listSupportedNetworkServices (Lists all network services provided by + &PRODUCT; or for the given Provider.) + + + addNetworkServiceProvider (Adds a network serviceProvider to a physical + network) + deleteNetworkServiceProvider (Deletes a Network Service + Provider.) + listNetworkServiceProviders (Lists network serviceproviders for a given + physical network.) + + + updateNetworkServiceProvider (Updates a network serviceProvider of a physical + network) + addTrafficType (Adds traffic type to a physical network) + deleteTrafficType (Deletes traffic type of a physical network) + + + listTrafficTypes (Lists traffic types of a given physical + network.) + updateTrafficType (Updates traffic type of a physical network) + listTrafficTypeImplementors (Lists implementors of implementor of a network + traffic type or implementors of all network traffic types) + + + createStorageNetworkIpRange (Creates a Storage network IP + range.) + deleteStorageNetworkIpRange (Deletes a storage network IP + Range.) + listStorageNetworkIpRange (List a storage network IP range.) + + + updateStorageNetworkIpRange (Update a Storage network IP range, only allowed + when no IPs in this range have been allocated.) + listUsageTypes (List Usage Types) + addF5LoadBalancer (Adds a F5 BigIP load balancer device) + + + configureF5LoadBalancer (configures a F5 load balancer device) + deleteF5LoadBalancer ( delete a F5 load balancer device) + listF5LoadBalancers (lists F5 load balancer devices) + + + listF5LoadBalancerNetworks (lists network that are using a F5 load balancer + device) + addSrxFirewall (Adds a SRX firewall device) + deleteSrxFirewall ( delete a SRX firewall device) + + + listSrxFirewalls (lists SRX firewall devices in a physical + network) + listSrxFirewallNetworks (lists network that are using SRX firewall + device) + addNetscalerLoadBalancer (Adds a netscaler load balancer + device) + + + deleteNetscalerLoadBalancer ( delete a netscaler load balancer + device) + configureNetscalerLoadBalancer (configures a netscaler load balancer + device) + listNetscalerLoadBalancers (lists netscaler load balancer + devices) + + + listNetscalerLoadBalancerNetworks (lists network that are using a netscaler + load balancer device) + createVirtualRouterElement (Create a virtual router element.) + configureVirtualRouterElement (Configures a virtual router + element.) + + + listVirtualRouterElements (Lists all available virtual router + elements.) + + + + + + +
diff --git a/docs/en-US/change-to-behavior-of-list-commands.xml b/docs/en-US/change-to-behavior-of-list-commands.xml index 4e53590a773..9065398ef62 100644 --- a/docs/en-US/change-to-behavior-of-list-commands.xml +++ b/docs/en-US/change-to-behavior-of-list-commands.xml @@ -1,89 +1,109 @@ - %BOOK_ENTITIES; ]> - -
- Change to Behavior of List Commands - There was a major change in how our List* API commands work in CloudStack 3.0 compared to 2.2.x. The rules below apply only for managed resources – those that belong to an account, domain, or project. They are irrelevant for the List* commands displaying unmanaged (system) resources, such as hosts, clusters, and external network resources. - When no parameters are passed in to the call, the caller sees only resources owned by the caller (even when the caller is the administrator). Previously, the administrator saw everyone else's resources by default. - When accountName and domainId are passed in: - - The caller sees the resources dedicated to the account specified. - If the call is executed by a regular user, the user is authorized to specify only the user's own account and domainId. - If the caller is a domain administrator, CloudStack performs an authorization check to see whether the caller is permitted to view resources for the given account and domainId. - - When projectId is passed in, only resources belonging to that project are listed. - When domainId is passed in, the call returns only resources belonging to the domain specified. To see the resources of subdomains, use the parameter isRecursive=true. Again, the regular user can see only resources owned by that user, the root administrator can list anything, and a domain administrator is authorized to see only resources of the administrator's own domain and subdomains. - To see all resources the caller is authorized to see, except for Project resources, use the parameter listAll=true. - To see all Project resources the caller is authorized to see, use the parameter projectId=-1. - There is one API command that doesn't fall under the rules above completely: the listTemplates command. This command has its own flags defining the list rules: - - - - - - - listTemplates Flag - Description - - - - - featured - Returns templates that have been marked as featured and public. - - - - self - Returns templates that have been registered or created by the calling user. - - - - selfexecutable - Same as self, but only returns templates that are ready to be deployed with. - - - - sharedexecutable - Ready templates that have been granted to the calling user by another user. - - - - executable - Templates that are owned by the calling user, or public templates, that can be used to deploy a new VM. - - - - community - Returns templates that have been marked as public but not featured. - - - - all - Returns all templates (only usable by admins). - - - - - The &PRODUCT; UI on a general view will display all resources that the logged-in user is authorized to see, except for project resources. To see the project resources, select the project view. -
+ Change to Behavior of List Commands + There was a major change in how our List* API commands work in CloudStack 3.0 compared to + 2.2.x. The rules below apply only for managed resources – those that belong to an account, + domain, or project. They are irrelevant for the List* commands displaying unmanaged (system) + resources, such as hosts, clusters, and external network resources. + When no parameters are passed in to the call, the caller sees only resources owned by the + caller (even when the caller is the administrator). Previously, the administrator saw everyone + else's resources by default. + When accountName and domainId are passed in: + + + The caller sees the resources dedicated to the account specified. + + + If the call is executed by a regular user, the user is authorized to specify only the + user's own account and domainId. + + + If the caller is a domain administrator, CloudStack performs an authorization check to + see whether the caller is permitted to view resources for the given account and + domainId. + + + When projectId is passed in, only resources belonging to that project are listed. + When domainId is passed in, the call returns only resources belonging to the domain + specified. To see the resources of subdomains, use the parameter isRecursive=true. Again, the + regular user can see only resources owned by that user, the root administrator can list + anything, and a domain administrator is authorized to see only resources of the administrator's + own domain and subdomains. + To see all resources the caller is authorized to see, except for Project resources, use the + parameter listAll=true. + To see all Project resources the caller is authorized to see, use the parameter + projectId=-1. + There is one API command that doesn't fall under the rules above completely: the + listTemplates command. This command has its own flags defining the list rules: + + + + + + + listTemplates Flag + Description + + + + + featured + Returns templates that have been marked as featured and + public. + + + self + Returns templates that have been registered or created by the calling + user. + + + selfexecutable + Same as self, but only returns templates that are ready to be deployed + with. + + + sharedexecutable + Ready templates that have been granted to the calling user by another + user. + + + executable + Templates that are owned by the calling user, or public templates, that can + be used to deploy a new VM. + + + community + Returns templates that have been marked as public but not + featured. + + + all + Returns all templates (only usable by admins). + + + + + The &PRODUCT; UI on a general view will display all resources that the logged-in user is + authorized to see, except for project resources. To see the project resources, select the + project view. + + diff --git a/docs/en-US/changed-apicommands-4.0.xml b/docs/en-US/changed-apicommands-4.0.xml new file mode 100644 index 00000000000..f851bf71b46 --- /dev/null +++ b/docs/en-US/changed-apicommands-4.0.xml @@ -0,0 +1,268 @@ + + +%BOOK_ENTITIES; +]> + +
+ Changed API Commands in 4.0 + + + + + + + API Commands + Description + + + + + + copyTemplate + prepareTemplate + registerTemplate + updateTemplate + createProject + activateProject + suspendProject + updateProject + listProjectAccounts + createVolume + migrateVolume + attachVolume + detachVolume + uploadVolume + createSecurityGroup + registerIso + copyIso + updateIso + createIpForwardingRule + listIpForwardingRules + createLoadBalancerRule + updateLoadBalancerRule + createSnapshot + + + The commands in this list have a single new response parameter, and no other + changes. + New response parameter: tags(*) + + Many other commands also have the new tags(*) parameter in addition to other + changes; those commands are listed separately. + + + + + rebootVirtualMachine + attachIso + detachIso + listLoadBalancerRuleInstances + resetPasswordForVirtualMachine + changeServiceForVirtualMachine + recoverVirtualMachine + startVirtualMachine + migrateVirtualMachine + deployVirtualMachine + assignVirtualMachine + updateVirtualMachine + restoreVirtualMachine + stopVirtualMachine + destroyVirtualMachine + + + The commands in this list have two new response parameters, and no other + changes. + New response parameters: keypair, tags(*) + + + + + listSecurityGroups + listFirewallRules + listPortForwardingRules + listSnapshots + listIsos + listProjects + listTemplates + listLoadBalancerRules + + The commands in this list have the following new parameters, and no other + changes. + New request parameter: tags (optional) + New response parameter: tags(*) + + + + + listF5LoadBalancerNetworks + listNetscalerLoadBalancerNetworks + listSrxFirewallNetworks + updateNetwork + + + The commands in this list have three new response parameters, and no other + changes. + New response parameters: canusefordeploy, vpcid, tags(*) + + + + + createZone + updateZone + + The commands in this list have the following new parameters, and no other + changes. + New request parameter: localstorageenabled (optional) + New response parameter: localstorageenabled + + + + listZones + New response parameter: localstorageenabled + + + + rebootRouter + changeServiceForRouter + startRouter + destroyRouter + stopRouter + + The commands in this list have two new response parameters, and no other + changes. + New response parameters: vpcid, nic(*) + + + + updateAccount + disableAccount + listAccounts + markDefaultZoneForAccount + enableAccount + + The commands in this list have three new response parameters, and no other + changes. + New response parameters: vpcavailable, vpclimit, vpctotal + + + listRouters + + New request parameters: forvpc (optional), vpcid (optional) + New response parameters: vpcid, nic(*) + + + + listNetworkOfferings + + New request parameters: forvpc (optional) + New response parameters: forvpc + + + + listVolumes + + New request parameters: details (optional), tags (optional) + New response parameters: tags(*) + + + + addTrafficMonitor + + New request parameters: excludezones (optional), includezones (optional) + + + + createNetwork + + New request parameters: vpcid (optional) + New response parameters: canusefordeploy, vpcid, tags(*) + + + + listPublicIpAddresses + + New request parameters: tags (optional), vpcid (optional) + New response parameters: vpcid, tags(*) + + + + listNetworks + + New request parameters: canusefordeploy (optional), forvpc (optional), tags + (optional), vpcid (optional) + New response parameters: canusefordeploy, vpcid, tags(*) + + + + restartNetwork + + New response parameters: vpcid, tags(*) + + + + enableStaticNat + + New request parameter: networkid (optional) + + + + createDiskOffering + + New request parameter: storagetype (optional) + New response parameter: storagetype + + + + listDiskOfferings + + New response parameter: storagetype + + + + updateDiskOffering + + New response parameter: storagetype + + + + createFirewallRule + + Changed request parameters: ipaddressid (old version - optional, new version - + required) + New response parameter: tags(*) + + + + listVirtualMachines + + New request parameters: isoid (optional), tags (optional), templateid + (optional) + New response parameters: keypair, tags(*) + + + + updateStorageNetworkIpRange + + New response parameters: id, endip, gateway, netmask, networkid, podid, startip, + vlan, zoneid + + + + + +