
	Version 9.6	SEARCH CONTENTS \| PDF BOOKS \| HOME UP PREV NEXT

— Virtualizing APIs Using the CentraSite Business UI —

Creating an API Proxy

CentraSite Business UI provides a wizard to create and publish a virtual copy (proxy) of the API.

To create and publish a proxy API, the following prerequisites must be met:

You must be a registered user in the CentraSite.

You must belong to one of the following roles:

This Role...	Allows you to...
CentraSite Administrator	Create a proxy API within any organization.
Runtime API Provider	Create a proxy API within a specified organization.
API Publisher	Publish a proxy API into one or more targets.

For more information about roles and permissions, see the online documentation section Users, Groups, Roles and Permissions > About Roles and Permissions.

You can virtualize an API of any one of the following types in Business UI: Service, XML Service, and REST Service.
You can publish an API of any one of the following types in Business UI: Virtual Service, Virtual XML Service, and Virtual REST Service.
Make sure that an API of the type "Service" has a WSDL file, and APIs of the type "XML Service" and "REST Service" have schema files associated to it.
Ensure that the webMethods Mediator is configured and running on the webMethods Integration Server.

Important:
Ensure that the webMethods Mediator property watt.server.auth.skipForMediator Property is set to true. For details, see Run-Time Governance Reference > Built-In Run-Time Actions Reference for APIs.

To create and publish a proxy API, you perform the following high-level steps:

Defining a New API Proxy
Configuring the Run-Time Actions for an API Proxy
Publishing an API Proxy

Defining a New API Proxy

You use the panel 1 in the Virtualize wizard to define a new proxy and endpoint for the API.

To create a new proxy API, the following prerequisites must be met:

You must belong to either one of the following roles:
- CentraSite Administrator
- Runtime Provider
You must have at least the instance-level Modify permission on that API.

To define a new proxy API

Display the details page of the API for that you want to create a virtual copy. For procedures, see the CentraSite online documentation section API Management Solutions > Viewing Details for an API.
On the API details page, click Virtualize to open the Virtualize wizard.

In panel 1 of the Virtualize wizard, specify the following fields:

In this field... Do the following...

In this field...	Do the following...
`Create a new virtual alias`	Enter a name for the API proxy. By default, CentraSite populates the proxy API's name with the display name that was specified for native API. If a proxy API with the same name already exists, CentraSite issues a warning message.
`Reconfigure an existing virtual alias`	Alternatively, if a native API has proxy APIs, use this option to adapt it to your requirements.
`Endpoint to be virtualized`	You will see a list of the available endpoints for the native API. Select an endpoint which you want to create as the proxy API by choosing its radio button.

Create a new virtual
                           alias

Enter a name for the API proxy.

By default, CentraSite populates the proxy API's name with the display name that was specified for native API.

If a proxy API with the same name already exists, CentraSite issues a warning message.

Reconfigure an existing virtual
                           alias

Alternatively, if a native API has proxy APIs, use this option to adapt it to your requirements.

Endpoint to be
                           virtualized

You will see a list of the available endpoints for the native API.

Select an endpoint which you want to create as the proxy API by choosing its radio button.

Click Next.

Note:
If you do not enter information into a required field, the system will alert you with a red error icon. Pointing to the icon shows a hint with an error description.

Configuring the Run-Time Actions for an API Proxy

You use the panel 2 of the Virtualize wizard to configure the policy governance behavior for a proxy API.

The policy governance behavior of a proxy API is defined by the three components: Policy Accordions, Run-Time Actions, and the Message Flow Stages.

Summary of the Policy Accordions
Summary of the Run-Time Actions
Summary of the Message Flow Stages

Summary of the Policy Accordions

The policy actions are classified into one of the following accordions:

Accordion	Use to...
Request Handling	Request handler allows receiving and transforming the incoming message from a client into a custom format as expected by the native API. For example, a Require HTTP / HTTPS action mandates that the incoming requests for an API are received over the HTTP and/or HTTPS protocol.
Policy Enforcement	Enforces the adherence to real-time policy compliance identifying/authenticating, monitoring, auditing, and measuring and collecting result statistics for an API.
Response Processing	Response handler allows processing of the response message coming from the native API into a custom format as expected by the client.
Error Handling	Error handlers are used to format and return error messages. Errors can occur at run-time for various reasons. For example, security errors occur if a username is not correctly validated or authorized; transformation errors occur if transformation action is unable to successfully transform a message; a routing error is raised if a routing endpoint is unavailable, and so on.

Summary of the Run-Time Actions

Actions are the core elements of stages in a message flow that define the handling of messages as they flow through a proxy API. The following table lists the actions you can configure for the proxy API's message flow, and links you to topics that describe the actions, including how to configure them.

This action...	Use to...	Available in Message Flow Stage...	Applicable for...
Request Handling > Protocol
Require JMS	Specify the JMS protocol for the API to accept and process the requests.	Receive	SOAP APIs.
Require HTTP / HTTPS	Specify the HTTP and/or HTTPS protocol, SOAP format (for a SOAP-based API), and the HTTP methods (for a REST-based API) for the API to accept and process the requests.	Receive	SOAP APIs. REST APIs.
Request Transformation	Invoke an XSL transformation in the incoming request before it is submitted to the an API.	Receive	SOAP APIs. REST APIs.
Invoke webMethods Integration Server	Invoke a webMethods Integration Server service to pre-process the request before it is submitted to the an API.	Receive	SOAP APIs. REST APIs.
Policy Enforcement > Authentication
HTTP Basic Authentication	Identify and validate the consumer's authentication credentials contained in the request's Authorization header using HTTP basic authentication mechanism.	Routing	SOAP APIs. REST APIs.
NTLM Authentication	Identify and validate the consumer's authentication credentials contained in the request's Authorization header using NTLM authentication mechanism.	Routing	SOAP APIs. REST APIs.
OAuth2 Authentication	Identify and validate the consumer's authentication credentials contained in the request's Authorization header using OAuth 2.0 authentication mechanism.	Routing	SOAP APIs. REST APIs.
Policy Enforcement > JMS Routing
JMS Routing Rule	Specify a JMS queue to which the Mediator is to submit the request, and the destination to which the an API is to return the response.	Routing	SOAP APIs.
Set Message Properties	Specify JMS message properties to authenticate client requests before submitting to the an APIs.	Routing	SOAP APIs.
Set JMS Headers	Specify JMS headers to authenticate client requests before submitting to the an APIs.	Routing	SOAP APIs.
Policy Enforcement > Logging and Monitoring
Log Invocation	Log request/response payloads to a destination you specify.	Enforce	SOAP APIs. REST APIs.
Monitor Service Performance	Monitor the run-time performance for a specific consumer, and defines the level of performance that the specified consumer should expect from the API.	Enforce	SOAP APIs. REST APIs.
Monitor Service Level Agreement	Monitor a user-specified set of run-time performance conditions for an API, and sends alerts to a specified destination when these performance conditions are violated.	Enforce	SOAP APIs. REST APIs.
Policy Enforcement > Routing
Straight Through Routing	Route requests directly to a native endpoint that you specify.	Routing	SOAP APIs. REST APIs.
Content Based Routing	Route requests to different endpoints based on specific values that appear in the request message.	Routing	SOAP APIs. REST APIs.
Load Balancing and Failover Routing	Routes the requests across multiple endpoints.	Routing	SOAP APIs. REST APIs.
Context Based Routing	Route requests to different endpoints based on specific values that appear in the request message.	Routing	SOAP APIs. REST APIs.
Set Custom Headers	Specify the HTTP headers to process the requests.	Routing	SOAP APIs. REST APIs.
Policy Enforcement > Security
Require SSL	Mandate that requests be sent via SSL client certificates, and can be used by both SOAP and REST APIs.	Enforce	SOAP APIs.
Require Signing	Mandate that a request's XML element (which is represented by an XPath expression) be signed.	Enforce	SOAP APIs.
Require Encryption	Mandate that a request's XML element (which is represented by an XPath expression) be encrypted.	Enforce	SOAP APIs.
Require Timestamps	Mandate that timestamps be included in the request header.	Enforce	SOAP APIs.
Require WSS SAML Token	Uses a WSS Security Assertion Markup Language (SAML) assertion token to validate API consumers.	Enforce	SOAP APIs.
Evaluate HTTP Basic Authentication	Identify the consumer against either the Registered Consumers list (the list of registered consumers in Mediator) or the Global Consumers list (the list of available users in Mediator). Validate the client's authentication credentials contained in the request's Authorization header against the list of users in the Integration Server on which Mediator is running.	Enforce	SOAP APIs. REST APIs.
Evaluate Hostname	Identify the consumer against either the Registered Consumers list (the list of registered consumers in Mediator) or the Global Consumers list (the list of available users in Mediator). Validate the client's IP address against the list of users in the Integration Server on which Mediator is running.	Enforce	SOAP APIs. REST APIs.
Evaluate IP Address	Identify the consumer against either the Registered Consumers list (the list of registered consumers in Mediator) or the Global Consumers list (the list of available users in Mediator). Validate the client's IP address against the list of users in the Integration Server on which Mediator is running.	Enforce	SOAP APIs. REST APIs.
Evaluate WSS Username Token	Identify the consumer against either the Registered Consumers list (the list of registered consumers in Mediator) or the Global Consumers list (the list of available users in Mediator). Validate the client's WSS username token against the list of users in the Integration Server on which Mediator is running.	Enforce	SOAP APIs.
Evaluate WSS X.509 Certificate	Identify the consumer against either the Registered Consumers list (the list of registered consumers in Mediator) or the Global Consumers list (the list of available users in Mediator). Validate the client's WSS X.509 token against the list of users in the Integration Server on which Mediator is running.	Enforce	SOAP APIs.
Evaluate XPath Expression	Identify the consumer against either the Registered Consumers list (the list of registered consumers in Mediator) or the Global Consumers list (the list of available users in Mediator). Validate the client's XPath expression against the list of users in the Integration Server on which Mediator is running.	Enforce	SOAP APIs. REST APIs.
Evaluate OAuth2 Token	Identify the consumer against either the Registered Consumers list (the list of registered consumers in Mediator) or the Global Consumers list (the list of available users in Mediator). Validate the client's IP address against the list of users in the Integration Server on which Mediator is running.	Enforce	SOAP APIs. REST APIs.
Evaluate Client Certificate for SSL Connectivity	Identify the consumer against either the Registered Consumers list (the list of registered consumers in Mediator) or the Global Consumers list (the list of available users in Mediator). Validate the client's certificate against the list of users in the Integration Server on which Mediator is running.	Enforce	SOAP APIs. REST APIs.
Policy Enforcement > Traffic Management
Throttling Traffic Optimization	Limit the number of API invocations during a specified time interval, and sends alerts to a specified destination when the performance conditions are violated. Avoid overloading the back-end services and their infrastructure, to limit specific consumers in terms of resource usage, etc.	Enforce	SOAP APIs. REST APIs.
Policy Enforcement > Validation
Validate Schema	Validate all XML request and/or response messages against an XML schema referenced in the WSDL.	Enforce	SOAP APIs.
Response Processing
Response Transformation	Invoke an XSL transformation in the SOAP response payloads from XML format to the format required by the consumer.	Response	SOAP APIs. REST APIs.
Invoke webMethods Integration Server	Invoke a webMethods Integration Server service to process the response from the an API before it is returned to the consumer.	Response	SOAP APIs. REST APIs.
Error Handling
Custom SOAP Response Message	Return a custom error message (and/or the native provider's service fault content) to the consumer when the native provider returns a service fault.	Response	SOAP APIs.

For more information about the individual run-time actions that are supported out-of-the-box, see the online documentation section Run-Time Governance Reference > Run-Time Actions Reference for APIs.

Summary of the Message Flow Stages

Message Flow defines the implementation of a (proxy) API.

A message flow is a sequence of stages representing a non-branching one-way processing path. Message flow is used for request, enforce, routing and response paths as well as for error handlers.

A message flow tree is constructed by chaining together actions of these top-level stages:

Stage	Description
Receive	Request stage is used for processing the request path of the Message Flow.
Enforce	Enforce stage is used for processing the enforcement path of the Message Flow. The enforce stage is used to identify and validate specific consumers invoking APIs, throttle traffic, log request/response payloads, and monitor run-time performance conditions.
Routing	Routing stage is used for processing the routing path of the Message Flow. The routing stage is used to perform request-response communication. It represents the boundary between request and response processing for the API. When the routing stage dispatches a request message, request processing is considered finished. When the routing stage receives a response message, response processing begins.
Response	Response stage is used for processing the response path of the Message Flow. In addition, response stage is used as error handler.

To configure the run-time actions for a proxy API, the following prerequisites must be met:

You must belong to either one of the following roles:
- CentraSite Administrator
- Runtime Provider
You must have at least the instance-level Modify permission on the proxy API.

When you configure the actions for a proxy API, keep the following points in mind:

When you drag an action from the Policy Actions area, the respective step in the Message Flow area highlights where the action fits in, this making the navigation from Policy Actions area to the Message Flow area more intuitive.
Not all stages support the full set of actions. Every action happens only within a respective step. For example, the "Evaluate" actions occur only on the Enforce step; while the"Routing" actions occur only on the Routing step.
Mediator executes the run-time actions configured for a proxy API in a predefined order.
Some actions are mutually dependent. That is, a specific action must be used in conjunction with another particular action. For example, a Message Flow area that includes the Set JMS Headers action must also include the JMS Routing Rule action.
Some actions are mutually exclusive. That is, a specific action cannot be used in conjunction with another particular action. For example, a Message Flow area that includes the JMS Routing Rule action cannot include the Straight Through Routing action.
Some of the actions are allowed to appear multiple times within a message flow step.

For those actions that can appear in a message flow only once (for example, Evaluate IP Address), Mediator will choose only one, which might cause problems or unintended results.
For information about the individual run-time actions that are supported out-of-the-box, see the online documentation section Run-Time Governance Reference > Run-Time Actions Reference for APIs.
For information about how Mediator executes actions (and how to avoid policy conflicts), see the online documentation section Run-Time Governance Reference > Built-In Run-Time Actions Reference for APIs > Action Evaluation Order and Dependencies .
You can view a tooltip text for any accordion by moving the cursor over the accordion name. The tooltip text gives a summary of the accordion’s purpose.
If you modify the run-time action for a proxy API that is already deployed to webMethods Mediator, CentraSite automatically redeploys the modified API.

Configuring the Run-Time Actions in Message Flow

To configure the run-time actions for a proxy API

In the Virtualize page, inspect the accordions in the Policy Actions area.
Expand an accordion node whose action you want to add to the Message Flow area.
Drag and drop the required action into the Message Flow area.
Repeat steps 2 and 3 until you obtain a list of actions in the Message Flow area.
In the Message Flow area, locate the action whose parameter you want to set or examine.
Mouse hover the action whose parameters you want to configure.
Choose the Configure icon to the right of the action name.
In the <action name> dialog box, set the values for the parameters as necessary.

Note:
If you do not enter information into a required field, the system will alert you with a red error icon. Pointing to the icon shows a hint with an error description.
Click OK to save the parameter settings.
You can remove an action from the Message Flow area using the Delete icon to the right of the action name.
Click Next.

Or:
You can choose to perform one of the following actions:
- Previous button to switch back to the previous Create a New Virtual Alias panel.
- Virtualize button to create the proxy API.
- Next button to go to the next Publish the API Proxy panel.
- Cancel button to abandon your unsaved settings.

Publishing an API Proxy

You use the panel 3 of the Virtualize wizard to define the targets and publish the proxy API to webMethods Mediator.

To publish a proxy API, the following prerequisites must be met:

You must belong to either one of the following roles:
- CentraSite Administrator
- API Publisher
You must have at least the instance-level Full permission on the proxy API.
webMethods Mediator must be configured and running on the webMethods Integration Server.
To expose a proxy API for consumption, make sure that the " Set API Publish Permissions" policy is active. If the policy is in the inactive state, you must activate it. By default, this policy is active.

The "Set API Publish Permissions" policy includes a "Set Permissions" action that grants the instance-level "View" permission for the proxy API to the users in "Everyone" group. In addition, you can use the option "Propagate permissions to dependent objects". For more information, see the description of the action in the online documentation section Built-In Design/Change-Time Actions Reference > Built-In Actions for Design/Change-Time Policies.

To publish a proxy API

From the Available Targets list, choose one or more targets in which you want to publish the API.

Or:
If you want to publish the proxy API across all the targets, select the All Targets checkbox.
In the Advanced Settings node, select the Expose to Consumers checkbox. This allows unauthorized consumers (guests) to search and access the API.
Click Publish.

When attempting to publish a proxy API, without selecting at least on target, a warning popup box appears.

Or:
You can choose to perform one of the following actions:
- Previous button to switch back to the previous Configure the Run-Time Actions panel.
- Virtualize button to create the proxy API, and publish at a later stage. For the description of how to publish a proxy API at a later stage, see the section Publishing an API Proxy
- Cancel button to abandon your unsaved settings.

SEARCH CONTENTS | PDF BOOKS | HOME UP PREV NEXT