Structure of the catalog-scoped user-defined policy YAML file

Review the required structure of the YAML file that contains your catalog-scoped user-defined policy.

The .yaml file for a catalog-scoped user-defined policy contains the following sections:

Specification version

Set the specification version by adding the following line to the beginning of the file: 

policy: 1.0.0

Information

Complete the information section with details about the policy by using the following syntax:

info:
  title: Title of policy
  name: shortnameofpolicy
  version: 1.0.0
  description: An example policy
  contact: 
    name: name1
    url: url1
    email: email1
where:
  • title is the title of the policy. Any string can be used, but the title should be kept short so that it can be displayed in the API Manager user interface.
  • name is the short name for the policy. Must be a single word, and contain only alphanumeric characters, and the - (dash) and _ (underscore) characters. The name is case-sensitive, and should be 20 characters or less so that it can be displayed in the API Manager user interface.
    Important: The policy short name must be different from the OpenAPI names of the built-in policies, otherwise it will cause a policy conflict in the API assembly definition. For a list of the OpenAPI built-in policy names, see execute. Also, consider including an appropriate unique prefix or suffix string in the short names of your user-defined policy to prevent possible name conflicts with future built-in policies.
    Note: The name: property must be identical to the Node.js module name.
  • version is the version number of the policy. This is a reserved property.
    Tip: The version.release.modification version numbering scheme is recommended, for example 1.0.0.
    Note: The info.version in policy.yaml must match the version indicated in package.json.
  • description (optional) is a short description of the policy.
  • contact (optional) is the contact information for the policy, where:
    • name (string) is the identifying name of the contact person or organization.
    • url (string) is the URL that points to the contact information.
    • email (string) is the email address of the contact person or organization.
For example:
info:
  title: Custom Invoke Policy
  name: custom-invoke
  version: 1.0.0
  description: Invokes httpbin
  contact:
    name: IBM DataPower Samples
    url: 'https://github.com/ibm-datapower/'
    email: steve-product-manager@ibm.com

Attach

Complete the attach section by specifying which types of API flow the policy can be attached to.

  • rest indicates that this policy can be attached to a REST API flow.
  • soap indicates that this policy can be attached to a SOAP API flow.

The attach section must contain at least one API flow type. If a policy can be attached to both API flow types, they must both be indicated in the attach section.

For example:
attach:
  - rest
  - soap

Gateways

Specify the DataPower® API Gateway, as follows:

gateways:
  - datapower-api-gateway

Properties

Complete the properties section by defining a JSON schema (based on JSON Schema Specification Draft 4, but rendered in YAML format) that contains the list of properties the policy will declare as required input. These properties are presented to the API author at development time, when the properties can be configured or mapped to values as required. The JSON schema defines a root object that contains the following JSON properties:

  • type
  • properties
  • required
The syntax and definition of these properties matches the JSON schema definition. The following code block shows an example of a simple schema that defines one required property (a_property):
properties:
  $schema: "http://json-schema.org/draft-04/schema#"
  type: object
  properties:
    a_property:
    label: a label
    description: a description
    type: a type
  required:
    - a_property
The root type of the schema must be an object, as shown in the example schema. You can define zero or more properties in the schema. Required properties are declared by using the required parameter, as shown in the example schema. The policy will not be accessible in the API Manager assembly editor, unless all the required properties have values. Each property is an object with the following items:
  • label is a short name for the property and is displayed in the Name column of the API Manager assembly editor.
  • description is a short description for the property and is displayed in the Description column of the API Manager assembly editor.
  • type must be one of the following primitives that are supported:
    • integer
    • number
    • string
    • boolean (this primitive is shown as a check box in the assembly editor)
    • array
  • default (optional) specifies a default value for the property.
  • enum (for properties with a type of string) is an array of valid values.
For example:
properties:
  $schema: 'http://json-schema.org/draft-04/schema#'
  type: object
  properties:
    test:
      label: Test Property
      description: Enter any value
      type: string
  required:
    - test

Assembly section

The assembly section defines the assembly policy flow that will be activated when the user-defined policy is invoked. For example:

assembly:
  execute:
    - invoke:
        version: 2.0.0
        title: custom-invoke
        header-control:
          type: blacklist
          values: []
        parameter-control:
          type: whitelist
          values: []
        timeout: 60
        verb: keep
        cache-response: protocol
        cache-ttl: 900
        stop-on-error: []
        target-url: 'http://httpbin.org/headers'
You can determine the correct content of this section in either of the following ways:
  • Define the assembly flow by using the graphical assembly editor in either the API Designer or API Designer user interface, then copy the assembly: section from the Source tab. For more information on defining an assembly flow in the user interface, see The Assemble view and API policies and logic constructs.
  • Code the policies in the execute: subsection of the assembly: section by hand; for details, see execute.

The assembly section can contain only the API Connect built-in policies. However, you can include a gatewayscript policy that references native DataPower configuration.