5 Using Actions to Manage and Manipulate API Traffic

About Action Chains

You implement actions on API request or response traffic using the Actions tab for each API. You drag and drop individual actions into the Request or Response action chain to make them take effect. When you drop an action, a pane appears with the action parameters for you to configure. Every action has at least one optional Instance ID parameter that you can use to create an informal alphanumeric version number to identify the action. Some of these parameters are optional and some required. If you get a fail message when you try to save your changes, the problem can be a missing parameter. See the Services Gatekeeper Partner and API Management Portal Online Help for details about the parameters for individual actions.

You can use the actions provided by Services Gatekeeper, or create your own actions to act on the request (or response) traffic for an API. You can set up actions chains to take a wide range of real-time effect on the request or response messages, such as identity management, mapping to support data formats and protocol changes, authorization, logging, monitoring, and statistics.

The sequence of actions in the action chain depends on the direction of the message flow. It is either application-initiated and traveling to the network, or server-initiated and traveling to the application. Some actions (such as identity management) are valid only in the request flow and some only in the response flow. Other actions (such as supporting protocol changes, validations) are common in that they are applicable in either direction. Services Gatekeeper does not allow you add an invalid action to an action chain.

When you position an action incorrectly in a chain, Partner and API Management Portal prompts you to ensure that the sequence of actions is valid for that direction.

Actions in Application-Initiated Flows

When an application sends a request that contains a call to an API subscribed to by the application, Services Gatekeeper processes it using all actions configured for it in order. Services Gatekeeper can receive and handle incoming HTTP requests such as SOAP, REST, or XML-RPC. Services Gatekeeper checks the incoming request and performs preconfigured tasks such as enforcing policy (associated with the service level agreement), translates the message as necessary (such as from JSON to XML format), and so on. In addition, it processes the action with any custom tasks you added to suit your requirements. Finally, Services Gatekeeper forwards the outbound request message to the server.

Actions in Server-Initiated Flows

Server-initiated flows occur when, for example, an application sets up a notification for an event. The server listens for the event and sends a notification to the application. The notification comes in to Services Gatekeeper as a request from the server and contains a call to an API subscribed to by the application. Services Gatekeeper receives the request from the server and processes it according to the response action chain. The final step in the action chain would be to forward the outbound request message to the application in the format required by that application.

When the application responds to this notification, the API proxy processes that response according to the tasks preconfigured for that sequence of the action chain. Finally, the response for the server-initiated request is sent back to the server.

Understanding Front and Middle Actions

Actions for both chains are divided into front actions and middle actions. Use front actions as major filters on the incoming requests. For example, you can use Throttling to regulate the usage of the API and regulate traffic based on specific partner groups. (API management already provides throttling based on the application and based on the network service.)

Use middle actions to act on the content of the request or response in real time. For example, use Callout to perform an HTTP GET operation against the Request URL and store the response as required.

About Action Statuses

You only change the action statuses if you create your own actions using the instructions in ”Creating Custom Actions for Your APIs” in Services Gatekeeper Portal Developer's Guide.

An action can have one these statuses:

• ACTIVE

  The Oracle-supplied actions, and any new actions you create in Partner and API Management Portal have a state of the ACTIVE.

  Any API can use an action the ACTIVE state.

• DEPRECATED

  A deprecated action represents an older version of a current interface. When you update an existing action, the updated version becomes the active version and the previous version becomes deprecated. You can also deprecate an existing action in Partner and API Management Portal, by selecting the icon adjoining the trash can icon within the interface icon. Services Gatekeeper asks you to specify the date and time when the interface should be deprecated.

  Tip:

  Maintain backward compatibility when you update an active action.

  The data for a deprecated action cannot be modified, and deprecated actions are not available to new APIs.

  The service associated with a deprecated action is available to APIs that subscribed to the interface and only for a designated period. After that period, the network service supplier can remove the deprecated interface.

Setting Actions System Performance Settings

You use the Actions system performance settings to ensure that your actions do not inadvertently include code that adversely affects Services Gatekeeper performance. The Actions system performance settings are listed here with the default value in parenthesis:

• KeepNorthSession Boolean (false) - If true, this setting keeps the session open after the request is complete

• EnableSouthCookie Boolean (false) - If true, allows applications to communicate with backend servers using cookies. You must set this to true if your Actions use basic (text-based) authentication.

• UseSession Boolean (false) - If true, allows an application to use a session when communicating with backend servers.

• MaxTotalConnections Integer (4000) - Sets the maximum total allowed network connections. You can also set this option from the system WebLogic server start up script; see "Using the Weblogic Startup Script to Set Action System Performance Settings" for details.

• SocketTimeoutMs Integer (30000) - The time, in milliseconds, that socket waits for activity before closing down. You can also set this option from the system WebLogic server start up script; see "Using the Weblogic Startup Script to Set Action System Performance Settings" for details.

• ConnectTimeoutMs Integer (30000) - The time, in milliseconds, that a connection waits for activity before closing down. You can also set this option from the system WebLogic server start up script; see "Using the Weblogic Startup Script to Set Action System Performance Settings" for details.

• ReuseAddress Boolean (true) - If true, allows Services Gatekeeper to make use of the normally unused extra time that TCP reserves before closing sockets (the time_wait state).

You have these options to change these settings:

• Edit the DafConfigurationsMBean directly. For details on DafConfigurationsMBean see the ”All Classes” section of the Actions Java API Reference documentation.

• Use the Services Gatekeeper Administration Console. See "Using the Administration Console to Set Action System Performance Settings" for details on using the Administration Console.

• See "Using the Weblogic Startup Script to Set Action System Performance Settings" for details on setting these Actions system performance parameters as startup script options.

% startWebLogic.sh -Doracle.sdp.daf.max_total_connections=3000

Setting Actions White and Black Lists

You use these ”white” and ”black” lists to control the individual methods and packages that software developers are allowed to us in actions. These are the default lists:

• Black list of methods: exit and setProperty.

• Black list of packages:

  • java.lang.Thread;java.lang.Runnable

  • java.lang.ClassLoader

  • java.lang.Class

  • java.io

  • java.net

  • groovy.lang.GroovyShell

  • groovy.util.Eva

  • groovy.io

  • groovy.net

• White list of methods: java.net.InetAddress.getLocalHost()

• White list of packages: null

To view or change the white and black lists using the Administration Console:

1. Start the Administration Console.

   See ”Starting and Using the Administration Console” in Services Gatekeeper System Administrator's Guide for details.

2. Click Lock & Edit.

3. Navigate to OCSG, then admin_server_name (Server1 by default), then Container Services, then DafGeneralInformation, then Operations.

   The Configuration and Provisioning on server_name page appears with the performance settings.

4. Select an operation from the Select An Operation menu. The choices are:

   • loadBlackListMethod - Add Java/Groovy methods to the black list.

   • loadBlackListPackage - Add Java/Groovy packages to add to the black list.

   • loadWhiteListMethod - Add Java/Groovy methods to the white list.

   • loadWhiteListPackage - Add Java/Groovy packages to the white list.

   • retrieveBlackListMethod - Show the list of the Java/Groovy methods on the black list.

   • retrieveBlackListPackage - Show the list of Java/Groovy packages on the black list.

   • retrieveListAll - Show the contents of all white and black lists.

   • retrievePerformanceSets - Show the Actions performance settings (set using Attributes).

   • retrieveWhiteListMethod - Show the list of all items on the white lists.

   • retrieveWhiteListPackage - Show the list of all packages on the white lists.

appKeyValidation

Authenticate an application and give it access to an API. Typically used when the application cannot identify itself by other means. Confirms that an application has permission to access a specific API using an application key. You identify the application key, and you can also test whether that key exists in a header, or in a query parameter inside the header.

Callout

A REST Call-out. Performs an HTTP GET operation against the RequestUrl and puts the response into the value of the storeResponse field for use by another action. You can use Callout to change attributes of the incoming request. This feature is also available to use in a Groovy script or custom action.

See Services Gatekeeper Partner and API Management Portal Online Help for an example.

CORS

Web pages are free to imbed some resources, such as images, from outside their own domain. Exceptions to this are fonts and AJAX (XMLHttpRequest) requests, which are usually restricted to the same domain that the parent web page itself is in. The ”cross-domain” AJAX requests in particular are forbidden because they represent glaring security risks.

The CORS action allows you to configure cross-origin resource sharing (CORS) to safely access third-party resources for your APIs. The default settings are empty, so CORS messages are not processed. After you add this action to an action chain, configure it to process the CORS messages that your implementation uses.

This is a security-based action, so put it as early in your middle action chain as you can. Also, having this early in the action chain allows you to take advantage of the Allow Non Verified Requests option which cancels action chain processing if the action fails. This can prevent unnecessary processing if this action fails.

See the CORS specification at the W2C Cross-Origin Resource Sharing website:

https://www.w3.org/TR/2014/REC-cors-20140116/

The configuration parameters give you the options to:

• Allow preflight requests, simple requests, or both.

• Decide whether to require credentials when calling the API.

• Allow or disallow all origin URIs, resource headers, or methods to call the API.

• Create ”white lists” of origins URIs, resource headers, or methods that are allowed to call the API.

• Decide whether to support credentials in the request.

• Decide whether to continue action chain processing if the CORS action does not pass validation.

• The maximum time a user agent is allowed to cache results.

See the Services Gatekeeper Partner and API Management Portal Online Help for details about the options, and example configurations.

Groovy

Use a Groovy language script to change any aspect of a request or response message. You can add Groovy code to change the message content, destination, status, and so on. The script can be as simple or complex as your implementation requires. This option requires knowledge of the Groovy programming language.

You use the Actions Java API to obtain content from the API request and response traffic to act on in the Groovy action. Start by looking through the HttpContext class for information about extracting elements from messages. That class uses the HttpMessage, HttpRequest, and HttpResponse classes and some of its own methods to retrieve elements from messages that you can then manipulate. These classes are available from the ”All Classes” section of the Actions Java API Reference.

See "Common Actions Programming Tasks" and ”Creating Custom Actions for Your APIs” in Services Gatekeeper Portal Developer's Guide for some Groovy code examples.

Json2Xml

This action takes text formatted for the JSON protocol from the body of the incoming request or response body, and translates it into XML format in the body of the outgoing request or response. Table 5-1 lists the parameters for this action:

For example, this JSON formatted text:

{
  "SendSms": { 
    "message":"my message 2",
    "senderName” : "senderName",
    "addresses” : "tel:123456",
    "@myattribute” : "foo”  }
}

Is translated in this XML format:

<SendSms myattribute="foo">
  <addresses>tel:123456</addresses>
  <senderName>senderName</senderName>
  <message>my message 2</message>
</SendSms>

See the "Xml2Json" action to translate XML input to JSON.

RateLimit

Restricts access to a URL for HTTP-to-HTTP communication. You set the allowable number of accesses for a configurable time period for a specific URL. Use multiple Ratelimit actions to further refine access policies. For example, allow 1000 messages to the URL per day, but only 1 per minute.

SchemaValidation

Services Gatekeeper validates an incoming request or outgoing response that accesses a web service API, based on the schema provided by you for the API.

Provide values for the first XSD in the fields under the unit numbered 0. The first in the list is the main XSD/WADL/WSDL. The other entries are referenced from the first entry in the list.

1. For the Content parameter, enter the actual XML Schema XSD content. Paste in a Schema in the Value column.

2. For the Name parameter, enter the reference to the entry in Content. Use this name from another action or Groovy action to retrieve the schema you entered for Content.

To add more units, click the - sign next to Un.... and repeat.

Throttling

Change a partner group name, rate (requests/second), quota period (days), and quota (requests per quota period) specified in the message. The data you are changing comes from the appropriate SLA.

Xml2Json

This action takes text formatted for the XML protocol from the body of the incoming request or response body, and translates it into JSON format in the body of the outgoing request or response. Table 5-2 lists the parameters for this action.

For example, this XML formatted text:

<SendSms myattribute="foo">
  <addresses>tel:123456</addresses>
  <senderName>senderName</senderName>
  <message>my message 2</message>
</SendSms>

Is translated into this JSON formatted text:

{
  "SendSms": { 
    "message":"my message 2",
    "senderName” : "senderName",
    "addresses” : "tel:123456",
    "@myattribute” : "foo”  }
}

See the "Json2Xml" action to translate JSON input into XML format.

XSLT

Use an Extensible Stylesheet Language script to change the XML-formatted body of the message.

Printing and Changing Message Content

To print the contents of a message in the request action chain, you use the getClientRequest operation to the httpContext class, with the getBodyAsType operation to messageBuilder class. For example:

println httpContext.getClientRequest().getBodyAsType(String.class)

Assume that a RESTful request message contains:

{
  "test" : {
    "bob" : "123"
  }
}

You could use this Groovy script to return the value 123:

def body = context.clientRequest.getBodyAsType(org.codehaus.jackson.JsonNode.class);println body.get("test").get("bob").getTextValue()

To print the contents of a message in the response action chain, you use the getSouthBoundResponse operation to the httpContext class, with the getBodyAsType operation to the messageBuilder operation. For example:

println httpContext.getSouthboundResponse().getBodyAsType(String.class)

In a Groovy script you could use:

HttpResponse httpResponse = (HttpResponse) context.getAttribute("myattribute");

And then:

def responseBody = httpResponse.getBodyAsType(org.codehaus.jackson.JsonNode.class);

To change a request action chain message value, you use:

• The withBodyAsObject(Object) operation. Once changed, you then read only the changed value using the getBodyAsObject(Object) operation. Both are in the messageBuilder class.

• The withBodyAsStream(input stream) operation. Once changed, you then read only the changed value with the getBodyAsStream operation. Both are in the messageBuilder class.

See the "All Classes" section of the Actions Java API Reference for details on all of these operations and classes.

Using Actions to Manipulate HTTP Query Parameters

During processing by Services Gatekeeper, you can set encoded HTTP query parameters for a request message using any of these components. The components are processed in this order so the last in order makes the final changes:

1. The URL in the original request message.

2. The API Service URL that you specify when you create or update the API.

3. The API resource Path that you set in the Resources table when you create or update the API

4. An action. You can use either the default Groovy action, or a custom action that you create for this purpose. There are several purpose-built methods in the Actions Java API Reference for this purpose. See "Using a Groovy or Custom Action to Manipulate Query Parameters" for details on these methods. Also see ”Creating Custom Actions for Your APIs” in Services Gatekeeper Portal Developer's Guide for information on how to create a custom action.

context.getSouthboundCallout().withQueryString("pathQueryStr=actionV3_1");

context.getSouthboundCallout().withoutQueryParameter("pathQueryStr3");
context.getSouthboundCallout().withQueryString("pathQueryStr3=actionV3_1");
context.getSouthboundCallout().withQueryParameter("reqQueryStr4=actionV4_2");
context.getSouthboundCallout().withoutQueryParameter("reqQueryStr4");

context.getSouthboundCallout().ignoreAllRequestQueryParametersb(true);

Using Actions to Translate Between REST and SOAP

This section explains how to map between SOAP and REST communication using the tools in an actions chain.

Original REST Input:
{
  "envelope": {
      "x":1,
      "y":2
  }
}
 
After Json2Xml action:
<envelope>
   <y>2</y>
   <x>1</x>
</envelope>

After XSLT action (final XML output):
<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope
 xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cal="http://www.parasoft.com/wsdl/calculator/">
<soapenv:Header/>
<soapenv:Body>
<cal:add>
<cal:x>1</cal:x>
<cal:y>2</cal:y>
</cal:add>
</soapenv:Body>
</soapenv:Envelope>

<?xml version="1.0" encoding="ISO-8859-1"?>
 
<xsl:stylesheet
        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        version="1.0">
 
  <xsl:output method="xml" indent="yes"/>
 
  <xsl:template match="/">
 
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cal="http://www.parasoft.com/wsdl/calculator/">
      <soapenv:Header/>
      <soapenv:Body>
        <cal:add>
          <cal:x><xsl:value-of select="envelope/x"/></cal:x>
          <cal:y><xsl:value-of select="envelope/y"/></cal:y>
        </cal:add>
      </soapenv:Body>
    </soapenv:Envelope>
  </xsl:template>
 
</xsl:stylesheet>