Cisco Elastic Service Controller 1.0 REST API Guide

Transcription

1 Cisco Elastic Service Controller 1.0 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.0 REST API Guide 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 ) 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 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

4 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 Resources managed by ESC: Tenants, Networks, Subnets, Users, ServiceCatalog, Deployments o GET operations are synchronous the request/response parameters are described with an example of a request/response o 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. o 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 o 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 It is recommended that the ESC north bound client generate internal ids within the scope of the ESC. 5

6 o 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 create tenant/user/network/subnet with Openstack matching name will fail, with callback POST 409 conflict delete tenant/user/network/subnet in delete of tenant/user/network/subnet, Openstack 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 internal_tenant_id Body String NB Client tenant ID name Body String Tenant name 7

8 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 client used for debugging and logging internal_tenant_id Template String Yes Internal 8

9 1..64 Tenant ID provided by ESC NB client Name Body String Yes Tenant name 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 esc-request-status Header String A message describing the status of the request Response(synchronous)Parameters Example 9

10 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 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 10

11 <?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: 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 11

12 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: 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> 12

13 13

14 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 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 14

15 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 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 16

17 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): 200 Error Response Codes: 400 Bad Request, 500 Internal Server Error 17

18 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> <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> 18

19 <network_id>5661d66b-6ac4-49ae-b744-a5593f4aafbb</network_id> <shared>false</shared> <tenant_id>4f384dfc667a4776bc3169da27d09db5</tenant_id> </network> </networks> Create Network for Tenant 19

20 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 network is shared across all tenants. By default, only administrativ e users can change this value. provider:network_type Body String No Provider 20

21 provider:physical_networ k network type for instance vlan 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 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 21

22 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 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:

23 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> 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 23

24 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 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 24

25 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 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 Response (synchronous) 26

27 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 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: 27

28 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 Name Style Type Description 29

30 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> <subnet_id>0ff5c75c-69fa-450f c1d1a4842f4</subnet_id> </subnet> <subnet> 30

31 <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 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. ip_version Body String No IP version. cidr Body String No IP range for this subnet, 32

33 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 request Response(synchronous)Parameters Example 33

34 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. 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. 34

35 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> 35

36 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 Client-Transaction-Id: Response 36

37 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> <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> 37

38 <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. callback Header String Yes URL to be used for callback Request Example: 38

39 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) 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 39

40 esctransaction-id esc-statuscode esc-statusmessage Header 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 4) Service-Catalog 40

41 List all services in ServiceCatalog Verb URI Description GET /v0/servicecatalog Lists registered services. 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/servicecatalog 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): Bad Request (400), Internal Server Error (500) Response Parameters Name Style Type Description esc-transaction-id Header String A unique internal transaction ID generated by ESC for every request Response Example: HTTP/ OK Content-Type: application/xml; charset=utf-8 41

42 Content-Length: 200 Date: Sun, 1 Jan :00:00 GMT ESC-Transaction-Id: <?xml version="1.0" encoding="utf-8"?> <services> <service_registration> <flavor> <ephemeral_disk_mb>0</ephemeral_disk_mb> <external_flavor_id>a54750af-2bbb-4d30-b da37366e0</external_flavor_id> <name>sample-service-definition-group_0-sample_vm1</name> <internal_flavor_id>d5258a0d-9f4f-4b60-a545-0f2882c07d67-flavor-00-00</internal_flavor_id> <memory_mb>4096</memory_mb> <root_disk_mb>0</root_disk_mb> <swap_disk_mb>0</swap_disk_mb> <vcpus>2</vcpus> </flavor> <flavor> <ephemeral_disk_mb>0</ephemeral_disk_mb> <external_flavor_id>33e495bd-23c6-486f-8e78-0b1877a6bd7d</external_flavor_id> <name>sample-service-definition-group_0-sample_vm2</name> <internal_flavor_id>d5258a0d-9f4f-4b60-a545-0f2882c07d67-flavor-00-01</internal_flavor_id> <memory_mb>4096</memory_mb> <root_disk_mb>0</root_disk_mb> <swap_disk_mb>0</swap_disk_mb> <vcpus>4</vcpus> </flavor> <disk> <cloud_init_support>true</cloud_init_support> <container_format>bare</container_format> <disk_bus>ide</disk_bus> <disk_format>qcow2</disk_format> <disk_prefix>sd</disk_prefix> <e1000_net>true</e1000_net> <external_image_id>9a cd-42fc-9faf- 7a0a1ae09435</external_image_id> <imageisenabled>false</imageisenabled> <name>sample-service-definition-group_0-sample_vm1</name> <internal_image_id>d5258a0d-9f4f-4b60-a545-0f2882c07d67-image-00-00</internal_image_id> <serial_console>true</serial_console> <src> </disk> <disk> <cloud_init_support>true</cloud_init_support> <container_format>bare</container_format> <disk_bus>ide</disk_bus> <disk_format>qcow2</disk_format> <disk_prefix>sd</disk_prefix> <e1000_net>true</e1000_net> <external_image_id>b2505bb c03-84b1-486d88ee644d</external_image_id> 42

43 <imageisenabled>false</imageisenabled> <name>sample-service-definition-group_0-sample_vm2</name> <internal_image_id>d5258a0d-9f4f-4b60-a545-0f2882c07d67-image-00-01</internal_image_id> <serial_console>true</serial_console> <src> </disk> <internal_service_registration_id>regsample</internal_service_registration_id> <external_service_registration_id>2dee7003-8f9d-4a1c-b2ebf2de1d3daafb</external_service_registration_id> </service_registration> </services> 43

44 Create/Register Service in ServiceCatalog Verb URI Description POST /v0/servicecatalog/{internal_service_reg istration_id} Registers a service to the ServiceCatal og Request Request Parameters: Name Style Type Requi Description red clienttransaction-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 internal_servi ce_registratio n_id Temaplate String reg.xml Body XML data model Yes Yes callback Internal Service Registration ID provided by ESC NB client. The service reg.xml data model Request Example: POST /v0/servicecatalog/123 HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Callback:/registerservicecallback <datamodel> <version>1.0</version> <service_definition>... </service_definition> </datamodel> Response (synchronous) 44

45 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 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: Created (200) Error Response Code(s): Bad Request (400), 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-status- Header String Code representing Http status code esc-statusmessage code Header String A message describing the response could be a success or error message reg.xml Body XML data model The service reg.xml data model Response Example: 45

46 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"?> <services> <service_registration> <flavor> <ephemeral_disk_mb>0</ephemeral_disk_mb> <external_flavor_id>a54750af-2bbb-4d30-b da37366e0</external_flavor_id> <name>sample-service-definition-group_0-sample_vm1</name> <internal_flavor_id>d5258a0d-9f4f-4b60-a545-0f2882c07d67-flavor-00-00</internal_flavor_id> <memory_mb>4096</memory_mb> <root_disk_mb>0</root_disk_mb> <swap_disk_mb>0</swap_disk_mb> <vcpus>2</vcpus> </flavor> <flavor> <ephemeral_disk_mb>0</ephemeral_disk_mb> <external_flavor_id>33e495bd-23c6-486f-8e78-0b1877a6bd7d</external_flavor_id> <name>sample-service-definition-group_0-sample_vm2</name> <internal_flavor_id>d5258a0d-9f4f-4b60-a545-0f2882c07d67-flavor-00-01</internal_flavor_id> <memory_mb>4096</memory_mb> <root_disk_mb>0</root_disk_mb> <swap_disk_mb>0</swap_disk_mb> <vcpus>4</vcpus> </flavor> <disk> <cloud_init_support>true</cloud_init_support> <container_format>bare</container_format> <disk_bus>ide</disk_bus> <disk_format>qcow2</disk_format> <disk_prefix>sd</disk_prefix> <e1000_net>true</e1000_net> <external_image_id>9a cd-42fc-9faf- 7a0a1ae09435</external_image_id> <imageisenabled>false</imageisenabled> <name>sample-service-definition-group_0-sample_vm1</name> <internal_image_id>d5258a0d-9f4f-4b60-a545-0f2882c07d67-image-00-00</internal_image_id> <serial_console>true</serial_console> <src> </disk> <disk> <cloud_init_support>true</cloud_init_support> <container_format>bare</container_format> <disk_bus>ide</disk_bus> 46

47 <disk_format>qcow2</disk_format> <disk_prefix>sd</disk_prefix> <e1000_net>true</e1000_net> <external_image_id>b2505bb c03-84b1-486d88ee644d</external_image_id> <imageisenabled>false</imageisenabled> <name>sample-service-definition-group_0-sample_vm2</name> <internal_image_id>d5258a0d-9f4f-4b60-a545-0f2882c07d67-image-00-01</internal_image_id> <serial_console>true</serial_console> <src> </disk> <internal_service_registration_id>regsample</internal_service_registration_id> <external_service_registration_id>2dee7003-8f9d-4a1c-b2ebf2de1d3daafb</external_service_registration_id> </service_registration> </services> 47

48 Get a specific registered Service in Service Catalog Ver URI b GET /v0/servicecatalog/{internal_service_registration _id} Description Get info for a specific registered service in the ServiceCatalo g 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 internal_servi ce_registratio n_id Temaplat e String Yes Internal Service Registration ID provided by ESC NB client. Request Example: GET /v0/servicecatalog/567 HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Response Response Codes Normal Response Code: 200 Error Response Code(s): 400 Bad Request, 500 Internal Server Error, 404 Resource Not found Response Parameters Name Style Type Description 48

49 esctransaction-id Header reg.xml Body XML data model external_servi ce_registratio n_id Body String A unique internal transaction ID generated by ESC for every request The service reg.xml data model String Service Registration ID generated by ESC 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"?> <services> <service_registration> <flavor> <ephemeral_disk_mb>0</ephemeral_disk_mb> <external_flavor_id>a54750af-2bbb-4d30-b da37366e0</external_flavor_id> <name>sample-service-definition-group_0-sample_vm1</name> <internal_flavor_id>d5258a0d-9f4f-4b60-a545-0f2882c07d67-flavor-00-00</internal_flavor_id> <memory_mb>4096</memory_mb> <root_disk_mb>0</root_disk_mb> <swap_disk_mb>0</swap_disk_mb> <vcpus>2</vcpus> </flavor> <flavor> <ephemeral_disk_mb>0</ephemeral_disk_mb> <external_flavor_id>33e495bd-23c6-486f-8e78-0b1877a6bd7d</external_flavor_id> <name>sample-service-definition-group_0-sample_vm2</name> <internal_flavor_id>d5258a0d-9f4f-4b60-a545-0f2882c07d67-flavor-00-01</internal_flavor_id> <memory_mb>4096</memory_mb> <root_disk_mb>0</root_disk_mb> <swap_disk_mb>0</swap_disk_mb> <vcpus>4</vcpus> </flavor> <disk> <cloud_init_support>true</cloud_init_support> <container_format>bare</container_format> <disk_bus>ide</disk_bus> <disk_format>qcow2</disk_format> <disk_prefix>sd</disk_prefix> <e1000_net>true</e1000_net> 49

50 <external_image_id>9a cd-42fc-9faf- 7a0a1ae09435</external_image_id> <imageisenabled>false</imageisenabled> <name>sample-service-definition-group_0-sample_vm1</name> <internal_image_id>d5258a0d-9f4f-4b60-a545-0f2882c07d67-image-00-00</internal_image_id> <serial_console>true</serial_console> <src> </disk> <disk> <cloud_init_support>true</cloud_init_support> <container_format>bare</container_format> <disk_bus>ide</disk_bus> <disk_format>qcow2</disk_format> <disk_prefix>sd</disk_prefix> <e1000_net>true</e1000_net> <external_image_id>b2505bb c03-84b1-486d88ee644d</external_image_id> <imageisenabled>false</imageisenabled> <name>sample-service-definition-group_0-sample_vm2</name> <internal_image_id>d5258a0d-9f4f-4b60-a545-0f2882c07d67-image-00-01</internal_image_id> <serial_console>true</serial_console> <src> </disk> <internal_service_registration_id>regsample</internal_service_registration_id> <external_service_registration_id>2dee7003-8f9d-4a1c-b2ebf2de1d3daafb</external_service_registration_id> </service_registration> </services> 50

51 Delete/Unregister Service in ServiceCatalog Verb URI Description DELETE /v0/servicecatalog/{ internal_service_registration _id } Deletes/Unregiste rs a registered service in the ServiceCatalog Request Request Parameters: Name Style Type Require d Description clienttransaction-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 internal_servi ce_registratio n_id Temaplat e String Yes callback Internal Service Registration ID provided by ESC NB client. Request Example: DELETE /v0/servicecatalog/567 HTTP/1.1 Host: client.host.com Content-Type: application/xml Accept: application/xml Client-Transaction-Id: Callback:/unregisterservicecallback Response (synchronous) Normal Response Code(s): 200 Error Response Code(s): Bad Request (400), Resource Not Found (404), Internal Server Error (500) Response(synchronous)Parameters Name Style Type Description esc-transaction-id Header String A unique internal 51

52 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: 204 Error Response Code(s): Bad Request (400), 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 52

53 53

54 5) Deployments Get All Deployments Verb URI Descri ption GET /v0/deployments Lists deploye d service s. 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/deployments/ 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): Bad Request (400), Internal Server Error (500) Response Parameters Name Style Type Description 54

55 esc-transaction-id Header String A unique internal transaction generated by ESC for every re external_service_deployment_id Body String Deployment ID generated by ES deployments_details Body XML See example below 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"?> <deployments> <deployment> <deployment_stage>vm_deployed</deployment_ stage> <deployment_details> <vm_uuid>26ebf6a5-812e a50-588c6579f70a</vm_uuid> <host_uuid>rereea5-812e a50-588c6579f70a</host_uuid> <interfaces> <network_uuid>0e89b2ed-5e79-47b2-9ff fc417ef</network_uuid> <ip_address> </ip_address> <port_uuid>c806c915-d5af-4269-bb6b-b76b66c720e1</port_uuid> <subnet_uuid>fd96c915-d5af-4269-bb6b-b76b66c720e1</subnet_uuid> <mac_address>fa:16:3e:01:ed:13</mac_address> </interface> </interfaces> <management_ip_address> </management_ip_address> <vm_name>sample-service-definition sample-tenant-01 dep-sample- 01 Group_0 sample_vm1 0</vm_name> </deployment_details> <external_deployment_id> f-a4e0-4d29-9ce2- ef90b94a65e8</external_deployment_id> <external_service_registration_id>2dee7003-8f9d-4a1c-b2ebf2de1d3daafb</external_service_registration_id> <external_tenant_id>4f384dfc667a4776bc3169da27d09db5</external_tenant_id> <internal_deployment_id>dep-sample-01</internal_deployment_id> <internal_service_registration_id>regsample</internal_service_registration_id> <internal_tenant_id>sample-tenant-01</internal_tenant_id> </deployment> </deployments> 55