Describing your policy

Describe your user-defined policy by creating a definition file in YAML format to document metadata about the policy.

About this task

A policy YAML file contains the following sections:

A specification version.
An information section.
An attach section.
A properties section.
A gateways section.

You can create a policy YAML file by using any editor of your choice. Both .yaml and .yml file extensions are supported, but the use of the .yaml file extension is recommended by yaml.org.

Note: IBM® API Connect Micro Gateway is deprecated in IBM API Connect Version 5.0.8 in favor of DataPower® Gateway. From 1 April 2020, Micro Gateway, and associated toolkit CLI commands, will no longer be supported. Existing users can migrate their API definitions to IBM DataPower Gateways. For information on supported API policies, see Built-in policies.

Note: All keys and enumeration values that are specified in this topic are case-sensitive.

Procedure

The following steps describe how to construct a policy YAML file.

Set the specification version by adding the following line to the beginning of the file: policy: 1.0.0.
Complete the information section with details about the policy by using the following syntax:
```
info:
  title: Title of policy
  name: <policy-name>
  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 and must contain only alphanumeric characters, the - (dash) character, and the _ (underscore) character (blank spaces are not supported). The name is case-sensitive, and should be 20 characters or less so that it can be displayed in the API Manager user interface. In the example, the name is shown as <policy-name>.
  Important: The policy short name must be different from the OpenAPI (Swagger 2.0) names of the built-in policies, otherwise it will cause a policy conflict in the API assembly definition. For a list of the OpenAPI (Swagger 2.0) built-in policy names, see execute.
  
  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.
Complete the attach section by specifying which type of API flow the policy can be attached to.
```
attach:
 - rest
 - soap
```
where:
- 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.
Note: The attach: property has no effect in the Micro Gateway.
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.
In your gateways section, specify which gateway that your policy is for.
- Enter the following code for a DataPower Gateway:
```
gateways:
  - datapower-gateway
```
- Enter the following code for a Micro Gateway:
```
gateways:
  - micro-gateway
```
- You can also target a policy for both gateways:
```
gateways:
  - datapower-gateway
  - micro-gateway
```
Save the new policy as a YAML file using the value of the name property (in the info section) as the file's name.

Required: To ensure a successful import, the YAML file must use the name specified in the policy's name property.

Results

You have created a user-defined policy definition YAML file that documents metadata about your policy.

Example

The following code block shows an example of a policy definition file that contains all the supported primitives. This policy must be saved as sampleimpl.yaml to ensure that it can be imported into API Connect.

policy: 1.0.0

info:
  title: Sample Policy
  name: sampleimpl
  version: 1.0.1
  description: This is a sample policy.
  contact: 
    name: Steve Product Manager
    url: http://developer.acme.com/contacturl
    email: steve-product-manager@someemailservice.com

attach:
  - rest
  - soap

properties:
  $schema: "http://json-schema.org/draft-04/schema#"
  type: object
  properties:
    samplestring:
      label: String Property
      description: Sample string property
      type: string
    sampleboolean:
      label: Boolean Property
      description: Sample boolean property
      type: boolean
    sampleinteger:
      label: Integer Property
      description: Sample integer property
      type: integer
    samplenumber:
      label: Number Property
      description: Sample number property
      type: number
    samplestringwithenum:
      label: Enum Property
      description: Sample string enum property
      enum:
        - one
        - two
        - three
      default: one
      type: string
    samplearray:
      label: Array of properties
      description: Sample array of properties
      type: array
      items:
        type: object
        properties:
          string:
            label: String Property
            description: Sample string property in array
            type: string
          boolean:
            label: Boolean Property
            description: Sample boolean property in array
            type: boolean
        required:
          - string
  required:
    - samplestring
    - sampleboolean
    - sampleinteger
    - samplenumber
    - samplearray

gateways:
  - datapower-gateway

In the following code block, an example of a policy definition file for modifying message payload is shown.

policy: 1.0.0

info:
  title: Run GatewayScript
  name: gatewayscript-policy
  version: 1.0.0
  description: Execute GatewayScript
  contact: 
    name: IBM DataPower Samples
    url: https://github.com/ibm-datapower/
    email: steve-product-manager@ibm.com

attach:
  - rest
  - soap

gateways:
  - datapower-gateway

properties:
  $schema: "http://json-schema.org/draft-04/schema#"
  type: object
  properties:
    source:
      label: "GatewayScript Source"
      description: "The location of the GatewayScript file to execute"
      type: string
      default: store:///identity.js
    value:
      label: "New Value"
      description: "The value to be added to the payload"
      type: string
      default: "Hello Policy"
required:
    - source
    - value

What to do next

Create an implementation for your user-defined policy by using DataPower processing rules and actions. For more information, see Implementing your policy.