Defining, packaging, and publishing a global-scoped policy for the API Gateway

Create a global-scoped, user-defined policy that is available to APIs in any of the catalogs in any provider organization.

About this task

When a global-scoped policy is published, you can use it in the API Assembler's Policy palette for APIs in any catalog belonging to any provider organization. Complete the following tasks to define, package, and publish the global-scoped policy.

Tip: During this task, you will create several zip files. On Mac OS X, run the zip command on the command line with the following flags:
-x ".DS_Store" -x "__MACOSX"

Including the flags prevents the auto-generated .DS_Store and __MACOSX files from being added to the zip.

Step 1: Define a global-scoped policy for API Gateway

Use the DataPower Web GUI to define a new policy that can be used in API assemblies in all catalogs belonging to all provider organizations.

Procedure

  1. Log in to the DataPower Web GUI.
  2. Create a new "test" domain and then switch to it.

    This test domain will be used as a "sandbox" to build and export the custom policies.

  3. Navigate to Assembly Function and create a new object:
    1. Name the object <policyname>_<version>.
      Example: "testpolicy_1.0.0". Use the same name for all of the objects that you create in this task. Because the policy will be available in all provider organizations and catalogs, there is no need to specify that information in the object name.
    2. Under the "Assembly" property, create a new Assembly.
    3. Under the new Assembly, create a new Rule.
    4. Under the new Rule, create a new API Action.
    5. Optionally add an implementation file for the new Action.

      For example, an XSLT Action requires an XSL file. Create the file in the using the following path and name (where "udp" refers to user-defined policy:

      local:///<udp-name>/<udp-name>.<file-extension>

    6. Click Apply and then save all of the new objects.
  4. Export the new user-defined policy.
    1. Navigate to the newly created Assembly Function.
    2. Click Export to export the new user-defined policy to a file named <policyname>_<version>.zip.
    3. Open the exported <policyname>_<version>.zip file and confirm that all referenced files are included.
    4. Delete the dp-aux folder from the zip.
      This optional folder requires a lot of storage space and might cause a problem when you package and publish the new policy in the next task.

Step 2: Package and publish a global-scoped policy for API Gateway

Decide how you want the new global-scoped policy to be managed, and then publish it to make it available to API assemblies.

About this task

Be sure to complete the steps in Step 1: Define a global-scoped policy for API Gateway before attempting to package and publish the new global-scoped policy. There are two methods for packaging and publishing a user-defined policy, based on how you want the policy to be managed:

Step 2, Option A: Package and publish a global-scoped policy directly in the DataPower configuration

Package and publish a global-scoped policy so it can be stored directly on the DataPower API Gateway.

About this task

When you store a global-scoped policy on the DataPower API Gateway, the policy exists in the gateway's startup domain configuration and will be unaffected by the API Manager lifecycle.

Procedure

  1. Import the <policyname>_<version>.zip file containing the new global-scoped policy to the application domain for every DataPower node in the cluster.
    Complete the following steps on every DataPower node in the cluster--if you omit a node, then the policy will not be available in the API Assembly's Policy palette.
    1. On the DataPower node, navigate to the "API Connect Gateway Service" object.
    2. Under the "User-defined policies" property, add a new Assembly Function by importing the <policyname>_<version>.zip file containing your new global-scoped policy.
    3. Click Apply, and then Save.
  2. Verify that the new global-scoped policy is available in the API Assembler's Policy palette.
    1. Log in to API Manager.
    2. Create an API.
    3. Open the API Assembler page and view the Policy palette; verify that your new global-scoped policy displays and can be added to the API.

Step 2, Option B: Package and publish a global-scoped policy as a gateway extension that API Connect manages

Package and publish a global-scoped policy as a gateway extension in API Connect.

Before you begin

The xml-manager must be enabled on the default domain of every gateway that will have a gateway-extension published to it.

About this task

When you publish a global-scoped policy as a gateway extension in API Connect, it is subject to the API Manager lifecycle.

Procedure

  1. Make a copy of the <policyname>_<version>.zip file containing your new global-scoped policy and remove the <version> number from the file name.

    This name change ensures that the relative path of the file meets the requirement to match the following regular expression: implementation\/[\w_-]+\.zip. You can retain the copy of the file with its original name for tracking purposes.

  2. Create a local folder named implementation and store the renamed zip file in that folder.
  3. Create a YAML file that describes the new global-scoped policy.
    1. Create a file named <policyname>.yaml.
    2. Paste the following content into the new file:
      policy: 1.0.0
      info:
        title: <policyname>
        name: <policyname>
        version: 1.0.0
        description: <description-here>

      Only the policy and info sections are needed in the <policyname>.yaml for this task.

    3. Save and close the file.
  4. Create a new zip file called <policyname>_<version>.zip that contains the following files:
    • The implementation folder
    • <policyname>.yaml
  5. Create a gateway-extension manifest.json file as explained in Gateway extensions manifest.

    The manifest contains one or more entries. The following example contains a sample entry for the new global-scoped policy and references the original policy <policyname>_<version>.zip file that you created in Step 1: Define a global-scoped policy for API Gateway:

                {
                    "filename": "<policyname>_<version>.zip",
                    "deploy": "immediate",
                    "type": "user-defined-policy",
                },
  6. Create a new zip file called gateway-extension.zip that contains the following files:
    • manifest.json
    • <policyname>_<version>.zip

      This is the file that you created in step 4 of this task (it contains the implementation folder and the <policyname>.yaml file).

  7. Publish the new gateway extension using one of the following methods:
    • API Connect toolkit CLI:

      Use the apic gateway-extensions:create command to publish the gateway extension (see toolkit CLI reference documentation).

    • Cloud Manager UI:

      Complete the following steps to publish the gateway extension from Cloud Manager:

      1. Log in to Cloud Manager.
      2. Click Topology > > Configure gateway extensions and upload your new gateway-extension.zip file.
  8. Verify that the new global-scoped policy is available in the API Assembler's Policy palette.
    1. Log in to API Manager.
    2. Create an API.
    3. Open the API Assembler page and view the Policy palette; verify that your new global-scoped policy displays and can be added to the API.