Cisco Elastic Service Controller 1.1 REST API Guide

Transcription

1 Cisco Elastic Service Controller 1.1 REST API Guide Cisco Systems, Inc. Cisco has more than 200 offices worldwide. Addresses, phone numbers, and fax numbers are listed on the Cisco website at

2 Cisco Elastic Service Controller 1.1 REST API Guide 2015 Cisco Systems, Inc. All rights reserved.

3 Contents PART 1 ESC REST API FOR NB CLIENTS... 5 Introduction ) Tenants... 7 List Tenants... 7 Create a Tenant... 8 Get a Tenant Delete a Tenant ) Networks List Networks for Tenant Create Network for Tenant Get Network for Tenant Delete Network for Tenant ) Subnets List Subnets for Tenant Create Subnet for Tenant Get Subnet for Tenant Delete Subnet for Tenant ) Images List Images Create an Image Get an Image Delete an Image ) Flavors List Flavors Create a Flavor Get a Flavor Delete a Flavor ) Service-Catalog List all services in ServiceCatalog Create/Register Service in ServiceCatalog Get a specific registered Service in Service Catalog Delete/Unregister Service in ServiceCatalog ) Deployments Get All Deployments

4 Create/Deploy Get a Specific Deployment Delete/Undeploy ESC Callback Event ) VM Operations Stop a specified VM Start a specified VM Reboot a specified VM Disable VM Monitoring on a specified VM Enable VM Monitoring on a specified VM ) VNF Operations Stop Service Start Service Reboot Service Disable Monitoring for VNF Enable Monitoring for VNF

5 PART 1 ESC REST API for NB Clients Introduction o o o o o Resources managed by ESC: Tenants, Networks, Subnets, Users, ServiceCatalog, Deployments GET operations are synchronous the request/response parameters are described with an example of a request/response POST, DELETE, PUT operations are asynchronous. The asynchronous design use the web hooks approach using two independent "one-way" invocations - one to start a long-running operation (Client to ESC) and the other one to notify a requester that it is completed (ESC to client) o The inbound representation of the operation request will contain a callback field, whose value is a URI where the client expects a callback. If this field is not present, no callback will be performed. o When the operation has completed (either successfully or unsuccessfully), ESC will perform a POST request to the callback URI, with an entity body containing the final status resource for this operation. o Client can match a completion report back to the original request by comparing the internal transaction ID field value to the one returned in the initial status response o ESC Clients are expected to provide a REST implementation for all the callbacks. All POST,DELETE,PUT operations that require request and/or response body must provide a header parameter for media type. Note, that ESC is currently tested to accept and return XML. For example: Content-Type: application/xml Accept: application/xml Some string parameters, such as id, name, are restricted by the underlying cloud provider, such as Openstack. The allowable range for these parameters is included in the Create section for each resource, in this notation: String minimum-length.. maximum length, for example, for Tenant name: String Generally, names are either (for Tenant/User) or (Network/Subnet/Flavor/Image/VM) Id (such as uuid) are restricted to 64 characters, such internal_id 1..64, external_id o ESC imposes this limitation / restriction concerning internal ids: internal id naming must conform the standards stated in RFC 3986 Uniform Resource Identifier (URI): Generic Syntax. See sections related to URI encoding, sections 2.2 Reserved Characters and 2.3 Unreserved Characters. ESC will accept an internal id specified in the request URL form the unreserved character set: unreserved = ALPHA / DIGIT / "-" / "." / "_ NOTE: the tilde ~ is not supported in the internal id character set the internal id received in a request must be unique within the scope of all the domain resources (tenant, network, subnet, service catalog, deployment ) For example, you cannot create 2 networks with the same internal_network_id, even if the networks are created in different tenants 5

6 o It is recommended that the ESC north bound client generate internal ids within the scope of the ESC. NOTE: Reusing ( recycling ) of internal ids is not recommended. This practice can lead to confusion in trouble shooting. ESC does not support Use Cases where Resources managed by ESC are modified directly in Openstack, that is, created/delete/updated out-of-band of ESC. The behavior for out-of-band modifications to Openstack of resources tenant/user/network/subnet/vm is as follows: Out-of-Band Action Result of ESC API call create tenant/user/network/subnet in Openstack delete tenant/user/network/subnet in Openstack create tenant/user/network/subnet with matching name will fail, with callback POST 409 conflict delete of tenant/user/network/subnet, previously created through ESC will fail, with callback POST 404 not found get of tenant/user/network/subnet will return details stored in esc_database create of tenant/user/network/subnet will fail, with callback POST 409 conflict update resource in Openstack tenant/user/network/subnet in esc database remains unmodified. The result is a mismatch between esc and Openstack delete vm in Openstack this will trigger ESC statemachine to perform recovery a new VM will be deploy reboot or shutdown vm in Openstack this will trigger ESC statemachine to perform recovery VM hard reboot will be attempted, followed by undeploy/deploy (if required) 6

7 1) Tenants List Tenants Note: All URIs listed in this document needs to be preceded by assuming is ESC IP and the REST interface is running with http and not https. For more info about running ESC REST interface over https please refer to ESC installation guide. Verb URI Description GET /v0/tenants List tenants Request Request Parameters: Name Style Type Required Description client-transaction-id Header String No Transaction ID supplied by ESC NB client used for debugging and logging Request Example: GET /v0/tenants HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Response Response Codes Normal Response Code(s): 200 Error Response Code(s): 400 Bad Request, 500 Internal Server Error Response Parameters Name Style Type Description external_tenant_id Body String Generated Openstack tenant ID 7

8 internal_tenant_id Body String NB Client tenant ID name Body String Tenant name enabled Body Boolean Indicates if tenant is enabled description Body String Description about the tenant Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT <?xml version="1.0" encoding="utf-8"?> <tenants> <tenant> <internal_tenant_id> </internal_tenant_id> <external_tenant_id> </external_tenant_id> <name>elie</name> <enabled>true</enabled> <description>a description...</description> </tenant> <tenant> <internal_tenant_id> </internal_tenant_id> <external_tenant_id> </external_tenant_id> <name>michael</name> <enabled>true</enabled> <description>a description...</description> </tenant> </tenants> Create a Tenant Verb URI Description POST /v0/tenants/{internal_tenant_id} Creates a tenant Request Request Parameters: Name Style Type Required Description client-transaction-id Header String No Transaction ID supplied by ESC NB 8

9 internal_tenant_id Template String Yes client used for debugging and logging Internal Tenant ID provided by ESC NB client Tenant name Name Body String Yes Enabled Body Boolean Yes Indicates if tenant is enabled description Body String No Description about the tenant callback Header String Yes URL to be used for callback Request Example: POST /v0/tenants/123 HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Callback:/createtenantcallback <?xml version="1.0" encoding="utf-8"?> <tenant xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <name>elie</name> <enabled>true</enabled> <description>a description...</description> </tenant> Response (synchronous) Normal Response Code(s): 200 Error Response Code(s): Bad Request (400), Internal Server Error (500) Response(synchronous)Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request 9

10 esc-request-status Header String A message describing the status of the request Response(synchronous)Parameters Example HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: ESC-Request-Status: ESC is processing the request Response (callback) Response Codes Normal Response Code(s): 200 Error Response Code(s): Conflict 409, Internal Server Error 500 Response(callback)Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request esc-status-code Header String Code representing Http status code esc-status-message Header String A message describing the response could be a success or error message external_tenant_id Body String Generated Openstack tenant ID name Body String Tenant name internal_tenant_id Body String Generated Openstack tenant ID enabled Body Boolean Indicates if tenant is enabled description Body String Description about the tenant 10

11 Response Example (Success): HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: ESC-Status-Code: 200 ESC-Status-Message: Success <?xml version="1.0" encoding="utf-8"?> <tenant> <external_tenant_id> </external_tenant_id> <internal_tenant_id> </internal_tenant_id> <name>elie</name> <enabled>true</enabled> <description>a description...</description> </tenant> Response Example (Failure): HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: ESC-Status-Code: 500 ESC-Status-Message: Internal Server Error <?xml version="1.0" encoding="utf-8"?> <tenant> </tenant> Get a Tenant Verb URI Description GET /v0/tenants/{internal_tenant_id} Get tenant information by ID Request Request Parameters: 11

12 Name Style Type Required Description Header String No Transaction ID supplied by ESC NB client used for debugging and logging clienttransaction-id internal_tenant_id Template String Yes Internal Tenant ID provided by ESC NB client Request Example: GET /v0/tenants/123 HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Response Response Codes Normal Response Code(s): 200 Error Response Code(s): 400 Bad Request, 500 Internal Server Error, 404 Resource Not found Response Parameters Name Style Type Description esc-transaction-id Body String A unique internal transaction ID generated by ESC for every request external_tenant_id Body String Generated Openstack tenant ID name Body String Tenant name enabled Body Boolean Indicates if tenant is enabled description Body String Description about the tenant Response Example: 12

13 HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: <?xml version="1.0" encoding="utf-8"?> <tenant> <external_tenant_id> </external_tenant_id> <name>elie</name> <enabled>true</enabled> <description>a description...</description> </tenant> Delete a Tenant Verb URI Description DELETE /v0/tenants/{internal_tenant_id} Deletes a tenant Request Request Parameters Name Style Type Required Description client-transaction-id Header String No Transaction ID supplied by ESC NB client used for debugging and logging internal_tenant_id Template String Yes Internal Tenant ID provided by ESC NB client callback Header String Yes URL to be used for callback Request Example: DELETE /v0/tenants/123 HTTP/1.1 13

14 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Callback:/deletetenantcallback Response (synchronous) Normal Response Code(s): 204 Error Response Code(s): Bad Request (400), Internal Server Error (500), 400 Resource Not Found Response(synchronous)Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request esc-request-status Header String A message describing the status of the request Response(synchronous)Parameters Example HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: ESC-Request-Status: ESC is processing the request Response(callback) Response Codes Normal Response Code(s): 200 Error Response Code(s): Internal Server Error 500 Response(callback)Parameters Name Style Type Description 14

15 esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request esc-status-code Header String Code representing Http status code esc-status-message Header String A message describing the response could be a success or error message Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: ESC-Status-Code: 200 ESC-Status-Message: Success 15

16 2) Networks List Networks for Tenant Verb URI Description GET /v0/{internal_tenant_id}/networks Lists networks to which the specified tenant has access. NOTE: a List request will return all shared networks. So networks that were created with a different internal_tenant_id that are shared will be returned. Request Request Parameters: Name Style Type Required Description Header String No Transaction ID supplied by ESC NB client used for debugging and logging clienttransaction-id internal_tenant_id Template String Yes Internal Tenant ID provided by ESC NB client Request Example: GET /v0/123/networks HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Response Response Codes Normal Response Code(s):

17 Error Response Codes: 400 Bad Request, 500 Internal Server Error Response Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request status Body String The network status. subnets Body List The associated subnets. name Body String The network name. admin_state_up Body Boolean A Boolean value that indicates the administrative status of the network. external_tenant_id Body String OpenStack tenant ID. external_network_id Body String OpenStack network ID. shared Body Boolean Indicates whether this network is shared across all tenants. By default, only administrative users can change this value. Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: <?xml version="1.0" encoding="utf-8"?> <networks> <network> <admin_state_up>true</admin_state_up> <external_network_id>9ad32b6f-bb65-4a09-b a7dfd00</external_network_id> <external_tenant_id>4f384dfc667a4776bc3169da27d09db5</external_tenant_id> <internal_network_id>sample-network-01</internal_network_id> <name>sample-network-01</name> <network_id>9ad32b6f-bb65-4a09-b a7dfd00</network_id> <shared>false</shared> <tenant_id>4f384dfc667a4776bc3169da27d09db5</tenant_id> </network> <network> <admin_state_up>true</admin_state_up> 17

18 <external_network_id>5661d66b-6ac4-49ae-b744- a5593f4aafbb</external_network_id> <external_tenant_id>4f384dfc667a4776bc3169da27d09db5</external_tenant_id> <internal_network_id>sample-network-02</internal_network_id> <name>sample-network-02</name> <network_id>5661d66b-6ac4-49ae-b744-a5593f4aafbb</network_id> <shared>false</shared> <tenant_id>4f384dfc667a4776bc3169da27d09db5</tenant_id> </network> </networks> 18

19 Create Network for Tenant Verb URI Description POST /v0/{internal_tenant_id}/networks/{ Creates a internal_network_id} network for tenant Request Request Parameters: Name Style Type Required Description client-transaction-id Header String No Transaction ID supplied by ESC NB client used for debugging and logging callback Header String Yes URL to be used for callback internal_tenant_id internal_network_id Template String Template String Yes Yes Internal Tenant ID provided by ESC NB client Internal Network ID provided by ESC NB client name Body String Yes Network name admin_state_up Body Boolean No Description about the tenant shared Body Boolean No Indicates whether this 19

20 network is shared across all tenants. By default, only administrativ e users can change this value. provider:network_type Body String No Provider network type for instance vlan provider:physical_networ k Body String No Provider physical network provider:segmentation_id Body String No Vlan ID Request Example: POST /v0/123/networks/567 HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Callback:/createnetworkcallback <?xml version="1.0" encoding="utf-8"?> <network xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <name>sample-network-01</name> <admin_state_up>true</admin_state_up> <shared>false</shared> </network> Response (synchronous) Normal Response Code(s): 200 Error Response Code(s): Bad Request (400), Internal Server Error (500), Conflict (409) Response(synchronous)Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request 20

21 esc-request-status Header String A message describing the status of the request Response(synchronous)Parameters Example HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: ESC-Request-Status: ESC is processing the request Response(callback) Response Codes Normal Response Code(s): 200 Error Response Code(s): Internal Server Error 500 Response(callback) Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request esc-status-code Header String Code representing Http status code esc-status-message Header String A message describing the response could be a success or error message status Body String The network status. name Body String The network name. admin_state_up Body Boolean A Boolean value that indicates the administrative status of the network. external_tenant_id Body String OpenStack tenant ID of network owner external_network_id Body String Openstack network ID. shared Body Boolean Indicates whether this 21

22 network is shared across all tenants. By default, only administrative users can change this value. Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: ESC-Status-Code: 200 ESC-Status-Message: Success <?xml version="1.0" encoding="utf-8"?> <network> <admin_state_up>true</admin_state_up> <external_network_id>9ad32b6f-bb65-4a09-b a7dfd00</external_network_id> <external_tenant_id>4f384dfc667a4776bc3169da27d09db5</external_tenant_id> <internal_network_id>sample-network-01</internal_network_id> <name>sample-network-01</name> <shared>false</shared> </network> 22

23 Get Network for Tenant Verb URI Description GET /v0/{internal_tenant_id}/networks/{inter nal_network_id} Shows information for the specified network NOTE: The GET request will return successfully only if the network was created under the tenant or if the network is shared. So it is valid to get a network created under a different tenant id, as long as the network was created as shared. Request Request Parameters: Name Style Type Required Description client-transaction-id Header String No Transaction ID supplied by ESC NB client used for debugging and logging internal_tenant_id Template String Yes Internal Tenant ID provided by ESC NB client internal_network_id Template String Yes Internal Network ID provided by ESC NB client Request Example: GET /v0/123/networks/567 HTTP/1.1 23

24 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Response Response Codes Normal Response Code(s): 200 Error Response Code(s): 400 Bad Request, 500 Internal Server Error, 404 Resource Not found Response Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request status Body String The network status. subnets Body List The associated subnets. name Body String The network name. admin_state_up Body Boolean A Boolean value that indicates the administrative status of the network. external_tenant_id Body String OpenStack tenant ID of network owner external_network_id Body String Openstack network ID. shared Body Boolean Indicates whether this network is shared across all tenants. By default, only administrative users can change this value. Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT 24

25 ESC-Transaction-Id: <?xml version="1.0" encoding="utf-8"?> <network> <admin_state_up>true</admin_state_up> <external_network_id>9ad32b6f-bb65-4a09-b a7dfd00</external_network_id> <external_tenant_id>4f384dfc667a4776bc3169da27d09db5</external_tenant_id> <internal_network_id>sample-network-01</internal_network_id> <name>sample-network-01</name> <network_id>9ad32b6f-bb65-4a09-b a7dfd00</network_id> <shared>false</shared> <tenant_id>4f384dfc667a4776bc3169da27d09db5</tenant_id> </network> 25

26 Delete Network for Tenant Verb URI Description DELET E /v0/{internal_tenant_id}/networks/{internal _network_id} Deletes the specified network and its associated resources. Request Request Parameters: Name Style Type Required Description client-transaction-id Header String No Transaction ID supplied by ESC NB client used for debugging and logging callback Header String Yes URL to be used for callback internal_tenant_id Template String Yes Internal Tenant ID provided by ESC NB client internal_network_id Template String Yes Internal Network ID provided by ESC NB client Request Example: DELETE /v0/123/networks/567 HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Callback:/deletenetworkcallback 26

27 Response (synchronous) Normal Response Code(s): 200 Error Response Code(s): Bad Request (400), Resouce Not Found (404), Internal Server Error (500) Response(synchronous)Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request esc-request-status Header String A message describing the status of the request Response(synchronous)Parameters Example HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: ESC-Request-Status: ESC is processing the request Response(callback) Response Codes Normal Response Code(s): 200 Error Response Code(s): Network In Use (409), Internal Server Error (500) Response(callback) Parameters Name Style Type Description esctransaction-id Header String A unique internal transaction ID generated by ESC for every request esc-statuscode Header String Code representing Http status code esc-statusmessage Header String A message describing the response could be a success or 27

28 error message Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: ESC-Status-Code: 200 ESC-Status-Message: Success 28

29 3) Subnets List Subnets for Tenant Verb URI Description GET /v0/{internal_tenant_id}/subnets Lists subnets to which the specified tenant has access. Request Request Parameters: Name Style Type Required Description Header String No Transaction ID supplied by ESC NB client used for debugging and logging clienttransaction-id internal_tenant_id Template String Yes Internal Tenant ID provided by ESC NB client Request Example: GET /v0/123/subnets HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Response Response Codes Normal Response Code(s): 200 Error Response Code(s): 400 Bad Request, 500 Internal Server Error Response Parameters 29

30 Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request name Body String Human-readable name for this subnet (might not be unique). external_tenant_id Body String OpenStack tenant ID of network owner external_network_id Body String Openstack network ID. allocation_pools Body List List of cidr sub-ranges that are available for dynamic allocation to ports. Syntax: <start> </start> <end> </end> gateway_ip Body String Default gateway used by devices in this subnet. ip_version Body String IP version. cidr Body String IP range for this subnet, based on the IP version. external_subnet_id Body String OpenStack subnet ID enable_dhcp Body Boolean Specifies whether DHCP is enabled for this subnet. Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: <?xml version="1.0" encoding="utf-8"?> <subnets> <subnet> <cidr> /24</cidr> <enable_dhcp>true</enable_dhcp> <external_network_id>9ad32b6f-bb65-4a09-b a7dfd00</external_network_id> <external_subnet_id>0ff5c75c-69fa-450f c1d1a4842f4</external_subnet_id> <external_tenant_id>4f384dfc667a4776bc3169da27d09db5</external_tenant_id> <gateway_ip> </gateway_ip> <internal_subnet_id>sample-subnet-01</internal_subnet_id> <ip_version>4</ip_version> <name>sample-subnet-01</name> <network_id>9ad32b6f-bb65-4a09-b a7dfd00</network_id> 30

31 <subnet_id>0ff5c75c-69fa-450f c1d1a4842f4</subnet_id> </subnet> <subnet> <cidr> /24</cidr> <enable_dhcp>true</enable_dhcp> <external_network_id>5661d66b-6ac4-49ae-b744- a5593f4aafbb</external_network_id> <external_subnet_id>c332ae2a eb9-ac39- cb554e0ccb63</external_subnet_id> <external_tenant_id>4f384dfc667a4776bc3169da27d09db5</external_tenant_id> <gateway_ip> </gateway_ip> <internal_subnet_id>sample-subnet-02</internal_subnet_id> <ip_version>4</ip_version> <name>sample-subnet-02</name> <network_id>5661d66b-6ac4-49ae-b744-a5593f4aafbb</network_id> <subnet_id>c332ae2a eb9-ac39-cb554e0ccb63</subnet_id> </subnet> </subnets> 31

32 32

33 Create Subnet for Tenant Verb URI Description POST /v0/{internal_tenant_id}/subnets/{interna l_subnet_id} Creates a subnet on a specified network. NOTE: a List request will return all subnets that are created in a shared network. So subnets that were created with a different internal_tenant_id that are in a shared network will be returned. Request Request Parameters: Name Style Type Requir ed clienttransaction-id name Body String internal_subnet_id internal_tenant_id internal_network_id Body Description Header String No Transaction ID supplied by ESC NB client used for debugging and logging Template String Template String String No Yes Yes Yes Human-readable name for this subnet (might not be unique). Internal Subnet ID provided by ESC NB client Internal Tenant ID provided by ESC NB client. Should be owner of the network Internal Network ID provided by ESC NB Client. Should be the Network ID with which this subnet is associated. allocation_pools Body List No List of cidr sub-ranges that are available for dynamic allocation to ports. Syntax: <start> </start> <end> </end> gateway_ip Body String No Default gateway used by devices in this subnet. 33

34 ip_version Body String No IP version. cidr Body String No IP range for this subnet, based on the IP version. enable_dhcp Body Boolea n No Specifies whether DHCP is enabled for this subnet. callback Body Header No URL to be used for callback Request Example: POST /v0/123/subnets/567 HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Callback:/createsubnetcallback <?xml version="1.0" encoding="utf-8"?> <subnet xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <name>sample-subnet-01</name> <internal_network_id>sample-network-01</internal_network_id> <enable_dhcp>true</enable_dhcp> <ip_version>4</ip_version> <cidr> /24</cidr> <gateway_ip> </gateway_ip> <allocation_pools> <start> </start> <end> </end> </allocation_pools> </subnet> Response (synchronous) Normal Response Code(s): 200 Error Response Code(s): Bad Request (400), Internal Server Error (500) Response(synchronous)Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request esc-request-status Header String A message describing the status of the 34

35 request Response(synchronous)Parameters Example HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: ESC-Request-Status: ESC is processing the request Response(callback) Response Codes Normal Response Code: Created 200 Error Response Codes: Conflict 409, Internal Server Error 500 Response(callback) Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request esc-status-code Header String Code representing Http status code esc-status-message Header String A message describing the response could be a success or error message name Body String Human-readable name for this subnet (might not be unique). external_tenant_id Body String OpenStack tenant ID of network owner external_network_id Body String Openstack network ID. allocation_pools Body List List of cidr sub-ranges that are available for dynamic allocation to ports. Syntax: <start> </start> <end> </end> gateway_ip Body String Default gateway used by devices in this subnet. ip_version Body String IP version. 35

36 cidr Body String IP range for this subnet, based on the IP version. external_subnet_id Body String Openstack subnet ID. enable_dhcp Body Boolean Specifies whether DHCP is enabled for this subnet. Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: ESC-Status-Code: 200 ESC-Status-Message: Success <?xml version="1.0" encoding="utf-8"?> <subnet> <cidr> /24</cidr> <enable_dhcp>true</enable_dhcp> <external_network_id>9ad32b6f-bb65-4a09-b a7dfd00</external_network_id> <external_subnet_id>0ff5c75c-69fa-450f c1d1a4842f4</external_subnet_id> <external_tenant_id>4f384dfc667a4776bc3169da27d09db5</external_tenant_id> <gateway_ip> </gateway_ip> <internal_network_id>sample-network-01</internal_network_id> <internal_subnet_id>sample-subnet-01</internal_subnet_id> <ip_version>4</ip_version> <name>sample-subnet-01</name> <allocation_pools> <start> </start> <end> </end> </allocation_pools> </subnet> 36

37 37

38 Get Subnet for Tenant Ver b GET URI /v0/{internal_tenant_id}/subnets/{internal_sub net_id} Description Shows information for a specified subnet. NOTE: The GET request will return successfully only if the subnet was created under the tenant or if the subnet is in a network that is shared. So it is valid to get a subnet created under a different tenant id, as long as the subnet is under a network created as shared. Request Request Parameters: Name Style Type Required Description Header String No Transaction ID supplied by ESC NB client used for debugging and logging clienttransaction-id internal_tenant_id Template String Yes Internal Tenant ID provided by ESC NB client internal_subnet_id Template String Yes Internal Subnet ID provided by ESC NB client. Request Example: GET /v0/123/subnets/789 HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml 38

39 Client-Transaction-Id: Response Response Codes Normal Response Code: 200 Error Response Codes: 400 Bad Request, 500 Internal Server Error, 404 Resource Not found Response Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request name Body String Human-readable name for this subnet (might not be unique). external_tenant_id Body String OpenStack tenant ID of network owner external_network_id Body String Openstack network ID. allocation_pools Body List List of cidr sub-ranges that are available for dynamic allocation to ports. Syntax: <start> </start> <end> </end> gateway_ip Body String Default gateway used by devices in this subnet. ip_version Body String IP version. cidr Body String IP range for this subnet, based on the IP version. external_subnet_id Body String Openstack subnet ID. enable_dhcp Body Boolean Specifies whether DHCP is enabled for this subnet. Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: <?xml version="1.0" encoding="utf-8"?> <subnet> <cidr> /24</cidr> 39

40 <enable_dhcp>true</enable_dhcp> <external_network_id>5661d66b-6ac4-49ae-b744- a5593f4aafbb</external_network_id> <external_subnet_id>c332ae2a eb9-ac39- cb554e0ccb63</external_subnet_id> <external_tenant_id>4f384dfc667a4776bc3169da27d09db5</external_tenant_id> <gateway_ip> </gateway_ip> <internal_subnet_id>sample-subnet-02</internal_subnet_id> <ip_version>4</ip_version> <name>sample-subnet-02</name> <network_id>5661d66b-6ac4-49ae-b744-a5593f4aafbb</network_id> <subnet_id>c332ae2a eb9-ac39-cb554e0ccb63</subnet_id> </subnet> Delete Subnet for Tenant Verb URI Description DELET E /v0/{internal_tenant_id}/subnets/{internal_su bnet_id} Deletes a specified subnet. Request Request Parameters: Name Style Type Required Description client-transaction-id Header String No Transaction ID supplied by ESC NB client used for debugging and logging internal_tenant_id Template String Yes Internal Tenant ID provided by ESC NB client internal_subnet_id Template String Yes Internal Subnet ID provided by ESC NB client. 40

41 callback Header String Yes URL to be used for callback Request Example: DELETE /v0/123/subnets/789 HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Callback:/deletesubnetcallback Response (synchronous) Normal Response Code(s): 200 Error Response Code(s): Bad Request (400), Internal Server Error (500) Response(synchronous)Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request esc-request-status Header String A message describing the status of the request Response(synchronous)Parameters Example HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: ESC-Request-Status: ESC is processing the request Response(callback) 41

42 Response Codes Normal Response Code: 200 Error Response Codes: Unauthorized (401), Not Found (404), Conflict (409), Internal Server Error (500) Response(callback) Parameters Name Style Type Description Header esctransaction-id esc-statuscode esc-statusmessage Header Header String A unique internal transaction ID generated by ESC for every request String Code representing Http status code String A message describing the response could be a success or error message Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: ESC-Status-Code: 200 ESC-Status-Message: Success 42

43 43

44 4) Images List Images Verb URI Description GET /v0/images Lists all images. NOTE: a List request will return all root images (i.e images not created by service registration). Request Request Parameters: Name Style Type Required Description clienttransaction-id Header String No Transaction ID supplied by ESC NB client used for debugging and logging Request Example: GET /v0/images HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Response Response Codes Normal Response Code(s): 200 Error Response Codes: 400 Bad Request, 500 Internal Server Error Response Parameters Name Style Type Description name Body String The image name. external_tenant_id Body String OpenStack tenant ID of image owner. 44

45 external_image_id Body String Openstack image ID. internal_tenant_id Body String ESC tenant ID of image owner. internal_image_id Body String Internal image ID. cloud_init_support** Body String container_format Body String Format of the container disk_bus Body String Root disk bus. disk_format Body String Format of the disk. imagechecksum Body String Hash of the image data used. imageisenabled** Body Boolean public Body Boolean Image visibility. Public or private. Default is public. serial_console** Body Boolean src Body String Image location as supplied in the request. ** These fields display default values and are not actually implemented. Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jul :00:00 GMT ESC-Transaction-Id: <?xml version="1.0" encoding="utf-8"?> <images> <image xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <cloud_init_support></cloud_init_support> <container_format>bare</container_format> <disk_bus>virtio</disk_bus> <disk_format>qcow2</disk_format> <e1000_net>false</e1000_net> <external_image_id>aa a-4d1e-a58a- 458c07d71268</external_image_id> <external_tenant_id>32c d744ff8781c9ea169aee97</external_tenant_id> <imagechecksum>133eae9fb1c98f45894a4e60d </imagechecksum> <imageisenabled>true</imageisenabled> <name>cirros-image-indep</name> <internal_image_id>cirros-image-indep</internal_image_id> <internal_tenant_id>systemadmintenantid</internal_tenant_id> <public>true</public> <serial_console>true</serial_console> 45

46 <src> x86_64-disk.img</src> <virtio_net>true</virtio_net> </image> </images> Create an Image Verb URI Description POST /v0/images/{internal_image_id} Creates an image Request Request Parameters: Name Style Type Requ Description ired client-transaction-id Header String No Transaction ID supplied by ESC NB client used for debugging and logging callback Header String Yes URL to be used for callback internal_image_id Template String Yes Internal Image ID provided by ESC NB client name Body String Yes Image name src Body String Yes Image location. disk_format Body String Yes Format of the disk. A valid value is vmdk, raw or qcow2. container_format Body String No Format of the container serial_console** Body Boolean No size* Body Integer No Size of the image sizeunit* Body String No Size unit e1000_net Body Boolean No True if image has 46

47 e1000 drivers virtio_net Body Boolean No True if image has VIRTIO drivers disk_bus Body String Yes Root disk bus. A valid value is ide, scsi or virtio. * Not suggested to use. ** These fields are not implemented. Request Example: POST /v0/images/cirros-image-indep HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Callback:/createimagecallback <?xml version="1.0" encoding="utf-8"?> <esc_datamodel xmlns=" <images> <image> <name>cirros-image-indep</name> <src>file://cisco/images/cirros x86_64-disk.img</src> <disk_format>qcow2</disk_format> <container_format>bare</container_format> <serial_console>true</serial_console> <disk_bus>virtio</disk_bus> </image> </images> </esc_datamodel> Response (synchronous) Normal Response Code(s): 200 Error Response Code(s): Bad Request (400), Internal Server Error (500), Conflict (409), User Not Found (404) Response(synchronous)Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request esc-request-status Header String A message describing the status of the 47

48 request Response(synchronous)Parameters Example HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jul :00:00 GMT ESC-Transaction-Id: ESC-Request-Status: Request submitted for create images.results will be sent to Response(callback) Response Codes Normal Response Code(s): 200 Error Response Code(s): Internal Server Error 500 Response(callback) Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request esc-status-code Header String Code representing Http status code esc-status-message Header String A message describing the response could be a success or error message name Body String The image name. external_tenant_id Body String OpenStack tenant ID of image owner. external_image_id Body String Openstack image ID. internal_tenant_id Body String ESC tenant ID of image owner. internal_image_id Body String Internal image ID. cloud_init_support** Body String container_format Body String Format of the container disk_bus Body String Root disk bus. disk_format Body String Format of the disk. imagechecksum Body String Hash of the image data 48

49 used. imageisenabled** Body Boolean size Body String The size of the image data, in bytes. public Body Boolean Image visibility. Public or private. Default is public. serial_console** Body Boolean src Body String Image location as supplied in the request. ** These fields just display default values and are not actually implemented. Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: ESC-Status-Code: 200 ESC-Status-Message: Image creation completed successfully. <?xml version="1.0" encoding="utf-8" standalone="yes"?> <image xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <cloud_init_support/> <container_format>bare</container_format> <disk_bus>virtio</disk_bus> <disk_format>qcow2</disk_format> <event_type>create_image</event_type> <external_image_id>bce8770b-bc4a-4be9-bc00-697fcc160201</external_image_id> <external_tenant_id>32c d744ff8781c9ea169aee97</external_tenant_id> <imagechecksum>133eae9fb1c98f45894a4e60d </imagechecksum> <imageisenabled>true</imageisenabled> <name>cirros-image-indep</name> <size> </size> <internal_image_id>cirros-image-indep</internal_image_id> <internal_tenant_id>systemadmintenantid</internal_tenant_id> <public>true</public> <serial_console>true</serial_console> <src>file://cisco/images/cirros x86_64-disk.img</src> </image> Get an Image Verb URI Description GET /v0/images/{internal_image_id} Shows information 49

50 for the specified image Request Request Parameters: Name Style Type Required Description client-transaction-id Header String No Transaction ID supplied by ESC NB client used for debugging and logging internal_image_id Template String Yes Internal Image ID provided by ESC NB client Request Example: GET /v0/images/cirros-image-indep HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Response Response Codes Normal Response Code(s): 200 Error Response Code(s): 400 Bad Request, 500 Internal Server Error, 404 Resource Not found Response Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for 50

51 every request name Body String The image name external_tenant_id Body String OpenStack tenant ID of image owner external_image_id Body String Openstack image ID internal_tenant_id Body String ESC tenant ID of image owner internal_image_id Body String Internal image ID cloud_init_support Body String Not supported** container_format Body String Format of the container disk_bus Body String Root disk bus disk_format Body String Format of the disk imagechecksum Body String Hash of the image data used imageisenabled Body Boolean Not supported** public Body Boolean Image visibility. Public or private. Default is public. serial_console Body Boolean Not implemented*** src Body String Image location as supplied in the request Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <image xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <cloud_init_support></cloud_init_support> <container_format>bare</container_format> <disk_bus>virtio</disk_bus> <disk_format>qcow2</disk_format> <external_image_id>9b65523e-a31d c20-48eae40368fc</external_image_id> <external_tenant_id>32c d744ff8781c9ea169aee97</external_tenant_id> <imagechecksum>133eae9fb1c98f45894a4e60d </imagechecksum> <imageisenabled>true</imageisenabled> <name>cirros-image-indep</name> <internal_image_id>cirros-image-indep</internal_image_id> <internal_tenant_id>systemadmintenantid</internal_tenant_id> <public>true</public> <serial_console>true</serial_console> 51

52 <src>file://cisco/images/cirros x86_64-disk.img</src> </image> Delete an Image Verb URI Description DELETE /v0/images/{internal_image_id} Deletes the specified image Request Request Parameters: Name Style Type Required Description client-transaction-id Header String No Transaction ID supplied by ESC NB client used for debugging and logging callback Header String Yes URL to be used for callback internal_image_id Template String Yes Internal Image ID provided by ESC NB client Request Example: DELETE /v0/images/cirros-image-indep HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Callback:/deleteimagecallback Response (synchronous) Normal Response Code(s):

53 Error Response Code(s): Bad Request (400), Resouce Not Found (404), Internal Server Error (500) Response(synchronous)Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request esc-request-status Header String A message describing the status of the request Response(synchronous)Parameters Example HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jul :00:00 GMT ESC-Transaction-Id: ESC-Request-Status: Request submitted for delete images.results will be sent to Response(callback) Response Codes Normal Response Code(s): 200 Error Response Code(s): Bad Request (400), Not Found (404), Internal Server Error (500), Not Acceptable (406) Response(callback) Parameters Name Style Type Description Header esctransaction-id esc-statuscode esc-statusmessage Header Header String A unique internal transaction ID generated by ESC for every request String Code representing Http status code String A message describing the response. Could be a success or error message 53

54 Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jul :00:00 GMT ESC-Transaction-Id: ESC-Status-Code: 200 ESC-Status-Message: Image deletion completed successfully. 54

55 5) Flavors List Flavors Verb URI Description GET /v0/flavors List flavors NOTE: a List request will return all root flavors (i.e flavors not created by service registration). Request Request Parameters: Name Style Type Required Description client-transaction-id Header String No Transaction ID supplied by ESC NB client used for debugging and logging Request Example: GET /v0/flavors HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Response Response Codes Normal Response Code(s): 200 Error Response Code(s): 400 Bad Request, 500 Internal Server Error Response Parameters Name Style Type Description name Body String Flavor name ephemeral_disk_mb Body String Specifies the size of a secondary ephemeral 55

56 data disk external_flavor_id Body String Openstack image ID internal_flavor_id Body String Internal flavor ID memory_mb Body String Amount of memory in Mega Bytes per VM instance public Body Boolean Flavor access root_disk_mb Body String Virtual root disk size swap_disk_mb Body String Optional swap space allocation for the instance vcpus Body String Number of virtual CPUs per VM instance Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 Content-Length: 200 Date: Sun, 1 Jul :00:00 GMT <?xml version="1.0" encoding="utf-8"?> <flavors> <flavor xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <ephemeral_disk_mb>0</ephemeral_disk_mb> <external_flavor_id>db0209a5-cf8a-4eaa-89a a</external_flavor_id> <name>myflavor1</name> <internal_flavor_id>myflavor1</internal_flavor_id> <memory_mb>512</memory_mb> <public>true</public> <root_disk_mb>0</root_disk_mb> <swap_disk_mb>0</swap_disk_mb> <vcpus>1</vcpus> </flavor> <flavor xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <ephemeral_disk_mb>0</ephemeral_disk_mb> <external_flavor_id>e31f517d-e0bf-44d2-8e3dcf70d22f809c</external_flavor_id> <name>myflavor2</name> <internal_flavor_id>myflavor2</internal_flavor_id> <memory_mb>512</memory_mb> <public>true</public> <root_disk_mb>0</root_disk_mb> <swap_disk_mb>0</swap_disk_mb> <vcpus>1</vcpus> </flavor> </flavors> 56