API Gateway Proxy Routing and Configuration

• Routing, page 1

• Configuration, page 2

• Recommendations, page 5

RoutingThe Cisco Hosted Collaboration Mediation Fulfillment API Gateway Proxy uses unique URLs to identifyeach routable application. URL query parameters are used to identify the node that is to receive a request.

The following is an example URL:https://example.com:8443/APIGatewayProxyWebService/proxy/cucm/soap/axl/?customer-name=ABC&cluster-name=Cluster-1

Clients do not usually have to create these URLs. A list of the URLs is available from the Application ReferenceDirectory.

Clients can also build these URLs dynamically, so it is important to document how the URLs are used forrouting:

• The host portion example.com:8443 identifies the routable address of the Cisco Hosted CollaborationMediation Fulfillment. This will be taken from the global address and port configuration. See GlobalAddress and Port Configuration, on page 4.

• The path parameters - /APIGatewayProxyWebService/proxy/cucm/soap/axl/ - identify the service.

• The query parameters wsdl&dm-name=vm-gateway also referred to as the routing parameters, identifythe actual routable application.

APIs are identified using URLs (refer to the example URL below ):

• Identifies the address

• Identifies the service

• Identifies the instance (for example, the server. Depending on the service, routing parameters identifythe instance. )

Example URL: https://192.16.8.10:8443/APIGatewayProxyWebService/proxy/cucm/soap/axl/?customer-name=ABC & cluster-name=Cluster-1

Cisco Hosted Collaboration Mediation Fulfillment API Gateway Proxy Developer Guide, Release 10.6(1) 1

Routing ParametersThe routing parameters vary based on the type of application to which the API Gateway Proxy is routingrequests.

If the routing ID is provided in the URL along with the Shared Data Repository hierarchy or names, routingID takes precedence and the request is routed based on the routing ID.

Note

API Gateway Proxy routes to various applications including:

• Unified Communication applications: Unified Communications Manager, Cisco Unity Connection,Cisco Unified Communications Manager IM and Presence Service.

1 Routing based on Shared Data Repository hierarchy/names.

• customer-name (required)

• cluster-name (required)

• node-name (optional: if not specified, the request will routed to the publisher)

2 Routing based on routing ID ( routing-id (required))

◦Domain Managers: Unified Communications Domain Manager, Unified Contact Center DomainManager.

1 Routing based on Domain Manager name (dm-name (required))

2 Routing based on routing ID (routing-id (required))

• Unified CCDM.

1 Routing based on Domain Manager name (dm-name (required))

2 Routing based on routing ID ( routing-id (required))

• Cisco Hosted CollaborationMediation Fulfillment Services: Shared Data Repository, HLM, Fulfillment,Service Inventory.

Routing parameters are not applicable.

ConfigurationConfiguration information is provided to developers for context in case they need to contact Cisco HostedCollaboration Mediation Fulfillment administrators to troubleshoot API issues.

Cisco Hosted Collaboration Mediation Fulfillment API Gateway Proxy Developer Guide, Release 10.6(1)2

API Gateway Proxy Routing and ConfigurationRouting Parameters

Shared Data Repository Infrastructure ConfigurationBecause the API Gateway Proxy leverages infrastructure information in the Shared Data Repository to routeAPI requests to the appropriate application, it is important that Shared Data Repository is configured properly.With respect to the API Gateway Proxy this configuration can take place either before or after the UnifiedCommunications applications are installed and running. The following methods can be used to configure theShared Data Repository:

• Manual configuration through the GUI

• Manual configuration through the Cisco HCS web service interface

• Configuration using sync services

For more information see http://www.cisco.com/en/US/partner/products/ps11363/prod_maintenance_guides_list.html

The following infrastructure information needs to be configured in the Shared Data Repository:

• Customers

• Clusters

• Application Instances (UC Application, Domain Manager)

• Network Addresses (The API Gateway Proxy routes to service provider space network addresses)

• Credentials (The API Gateway Proxy uses the administration credentials associated with the applications)

For routing to work, each application must be configured properly in the Shared Data Repository. The APIGateway Proxy will route to:

UC Application (Unified Communications Manager, Cisco Unity Connection, Cisco Unified Presence)

• If routing is based on Shared Data Repository hierarchy/names, each UC application should have:

• An association to a cluster

• That cluster should have an association to a customer

• The application node itself should have valid credentials

• The application node itself should have valid network addresses (that are routable from CiscoHCM-F)

• If routing is based on routing ID, each application should have a routing ID. See Routing IDConfiguration, on page 4

Domain Manager (Unified Contact Center Domain Manager, Unified Communications Domain Manager)

• If routing is based on Shared Data Repository hierarchy/names then each domain manager should have:

• A unique domain manager name

• The domain manager node itself should have valid credentials

• The domain manager node itself should have valid network addresses (that are routable fromCiscoHCM-F)

Cisco Hosted Collaboration Mediation Fulfillment API Gateway Proxy Developer Guide, Release 10.6(1) 3

API Gateway Proxy Routing and ConfigurationShared Data Repository Infrastructure Configuration

• If routing is based on routing ID, each application should have a routing ID. See Routing IDConfiguration, on page 4

Cisco Hosted Collaboration Mediation Fulfillment –No configuration is required for routing to Cisco HostedCollaboration Mediation Fulfillment.

Only properly configured applications are routable. Once an application is properly configured, its uniqueURL and link to specifications will display in the Application Reference Directory.

Routing ID ConfigurationBy default, Cisco Hosted Collaboration Mediation Fulfillment will use hierarchical name-based routing thatis based on the infrastructure configuration in the Shared Data Repository. If a partner decides instead to usea unique identifier based on information that is already within their provisioning system, they can configurea routing ID. Routing ID is an optional field that can be configured as required.

The following support Routing ID:

• Unified Communications Manager

• IM and Presence Service

• Cisco Unity Connection

• Unified Contact Center Domain Manager

• Unified Communication Domain Manager

The routing ID can be configured through the Cisco HCM-F GUI or Cisco HCM-F Web Service Interface.If a routing ID is configured for an application, its unique URL (in the Application Reference Directory) isbuilt using the routing ID.

Global Address and Port ConfigurationThe following information can be configured by using the Cisco Hosted Collaboration Mediation Fulfillmentcommand line interface (CLI):

• Global address

• Global HTTP port

• Global HTTPS port

The global address is an address that is routable from all clients. If a load balancer exists in the topology,Cisco recommends that you use the global address as the address (or virtual IP address) of the load balancer.The global HTTPS port is only used for services that return an HTTP response, which is currently limited tojust Unified CCDMasynchronous responses. Otherwise, the global HTTPS port will be used. The configurationof the Global Address and Port is used as follows:

•When the global address is configured, it will be used with the global HTTPS port when we advertiseURLs in the Application Reference Directory. This allows clients to communicate with the API GatewayProxy using an address that is routable from the client network.

•When a client creates a subscription that may trigger asynchronous notifications, the API Gateway Proxyoverwrites the notify-to address of the client with that of the global address. This is currently the only

Cisco Hosted Collaboration Mediation Fulfillment API Gateway Proxy Developer Guide, Release 10.6(1)4

API Gateway Proxy Routing and ConfigurationRouting ID Configuration

scenario where the global HTTPS port is used, since the notifications will be HTTPmessages. This way,notifications are delivered through the API Gateway Proxy.

With respect to the API Gateway Proxy, as long as the global address and port configuration is correct theorder in which the configuration is completed is not relevant. For more information, see the followingdocuments:

• Cisco Hosted Collaboration Mediation Fulfillment Command Line Interface Reference Guide, Release10.6(1)

RecommendationsIt is recommended that:

• Clients re-use connections when communicating with the API Gateway Proxy.

• Clients enable cookies, and re-use http sessions when communicating with the API Gateway Proxy.

• Clients must ensure that all parts of the URLs they use to communicate with the API Gateway Proxyare configurable. This includes the hostname, port, and paths.

• That a DNS be available to speed the establishment of new sessions between the API Gateway andManagement Components.

Cisco Hosted Collaboration Mediation Fulfillment API Gateway Proxy Developer Guide, Release 10.6(1) 5

API Gateway Proxy Routing and ConfigurationRecommendations

Cisco Hosted Collaboration Mediation Fulfillment API Gateway Proxy Developer Guide, Release 10.6(1)6

API Gateway Proxy Routing and ConfigurationRecommendations