Manage Custom Fields

Custom fields provide API and application metadata that API Gateway administrators can use in their policies by way of context variables. The metadata can give policies more flexibility for processing messages between applications and APIs.
apip43
Custom fields provide API and application metadata that API Gateway administrators can use in their policies by way of context variables. The metadata can give policies more flexibility for processing messages between applications and APIs.
For example, a policy can use the value of an API custom field. The policy can use the value to route requests to the API on either the production server or the sandbox server.
As another example, a policy can use the value of an application custom field to return:
  • A product coupon if the request came from a mobile app.
  • A product catalog if the request came from a desktop application.
For more information about how to write policies and how to use context variables, see "Context Variables" in the API Gateway online documentation.
In this article:
 
 
Example: Add and Use a Custom API Field
The following example illustrates how Gateway administrators and API publishers can work together to add and use a custom API field:
  1. During planning, API owners and Gateway administrators decide they want the Gateway to cache calls that are sent to select APIs to prevent redundant calls from overwhelming those APIs. They decide to add a custom 
    API
     field to the 
    API Portal
    . For each API, the API owner uses the custom API field to specify whether to cache calls to the API. A context variable in the policy returns the value of the custom 
    API
     field by way of a standard service property.
  2. During implementation:
    1. The API owner adds the 
      API Cache
       custom API field and gives the field that the value set Yes/No.
    2. The Gateway administrator adds the 
      ${service.property.APICache}
       context variable to a policy. The administrator writes policy that caches calls to the API if the value of the 
      ${service.property.APICache}
       context variable is 
      Yes
      . Every 30 seconds, the policy retrieves calls from the API cache and sends them to the API.
       Administrators can review the names and values of custom 
      API
       fields that are assigned to APIs. For more information, see the "View Metadata Assigned to APIs" section.
  3. The API owner publishes the 
    Billing
     API on 
    API Portal
     and uses the 
    API Cache
     custom API field to assign the value 
    Yes
     to the API.
  4. The next time that the Gateway synchronizes with 
    API Portal
    , the Gateway gets the value that is assigned to the 
    Billing
     API (
    Yes
    ) and assigns it to the 
    ${service.property.APICache}
     context variable.
  5. During run time, when the Gateway receives calls to the 
    Billing
     API, the policy sends the calls to the 
    Billing
     API cache.
View Metadata Assigned to APIs
You can view metadata assigned to an API using the API Gateway and Policy Manager.
You can also list the names and values of metadata assigned to an API using the 
API Portal
 or by way of the Portal API.
For more information about the Portal API, see Portal API (PAPI).
 
Follow these steps:
 
  1. Log in to the API Gateway as an administrator. 
  2. Locate the API in the 
    Portal APIs
     folder.
  3. Right-click the name of the API and select 
    Service Properties
    .
    In the Published Service Properties dialog, the General tab lists the custom API fields and the assigned values for the API. The following image shows an example of the General tab:
    customappfield_apiserviceproperties.png  
Example: Add and Use a Custom Application Field
The following example illustrates how Gateway administrators and API publishers can add and use a custom application field:
  1. During planning:
    1. API owners and Gateway administrators decide to support the ability of their APIs to return different kinds of content to web applications based on whether the applications calling the API are built on mobile or desktop browsers. 
    2. Hence, they decide to add a custom application field to the 
      API Portal
      . This custom field requires that the organization administrator or API developer to specify the browser type for each of their applications.
  2. During implementation:
    1. The API owner adds the 
      Browser Type
       custom application field
       
      and gives it the value set 
      Mobile/Desktop
      .
    2. The Gateway administrator writes policy that, when a mobile app calls the Product API, requests product coupon data from the product database and returns it to the mobile app. If a desktop application calls the product API, then the policy requests product catalog data from a database and returns it to the desktop application. The administrator uses the 
      customFieldsMetadata
       context variable to integrate the custom field with the policy.
      For more information, see the "Integrate Custom Application Fields with Policies" section.
  3. An organization administrator adds the 
    Dog Food
     mobile application to 
    API Portal
     and uses the 
    Browser Type
     custom application field to assign the value 
    Mobile
     to the API.
  4. The next time that the Gateway syncs with the 
    API Portal
    , the 
    Dog Food
     mobile application API key carries the custom field name and value to the Gateway, which saves it in the OTK database.
  5. When the Gateway receives calls from the 
    Dog Food
     mobile application to the
     
    Product API, the policy gets the name and value of the application 
    Browser Type
     custom field in the 
    customFieldsMetadata
     context variable from the OTK database. Because the value of the application 
    Browser Type
     custom application field is 
    Mobile
    , the policy requests product coupon data from the product database and returns it to the app.
Integrate Custom Application Fields with Policies
Include the following steps in the policy:
  1. Retrieve the 
    customFieldsMetadata
     context variable. This context variable contains the name and value in JSON format for all custom application fields in an application.
  2. Evaluate the 
    customFieldsMetadata
     JSON value to extract a specific custom application field.
     The names of custom fields are concatenated.
  3. Assign the value of the custom field to a context variable.
The following figure shows an example policy snippet that integrates the 
Browser Type
 custom application field into a policy:
  customappfield_policycode5.png  
To view the metadata that is assigned to an application, use the 
API Portal
 or the Portal API.
Custom Application Fields and Policy Templates
The 
API Portal
 standard policy templates set the 
customFieldsMetadata
 context variable. The following image shows the relevant snippet for the Standard Policy Template Fragment - API Key. If API Gateway administrators customize, or create, policy templates, they must ensure that their policy templates set this context variable.
  customappfield_policytemplatecode1.png  
Manage Custom Fields
This section describes how to add, edit, enable, disable, and delete custom fields in the 
API Portal
. Administrators and API owners can add custom API and application fields to the 
API Portal
. Custom fields provide a menu of options or a text input field. After an administrator or an API owner adds a custom 
API
 field the 
API Portal
, when API developers add or edit an API, they can assign a value to the API using that custom field. After an administrator or an API owner adds the custom 
application
 field the 
API Portal
, when API developers add or edit an application, they can assign a value to the application using that custom field.
Custom 
API
 fields are available only to APIs that are published on the 
API Portal
. If the API is published on the API Gateway, the fields are not available to the API.
You can also manage your custom fields by way of the Portal API (PAPI) or use this API in your scripts for managing custom fields.
For more information about the Portal API, see Portal API (PAPI).
Add Custom Fields
  1. Select the 
    Services 
    icon, and select 
    Administration
    .
  2. Select 
    Custom Fields
    .
  3. Select 
    Add Custom Field
    .
  4. Complete the following fields, and then select 
    Save
    :
     
    Field Name
     
    Defines the name for the field you are adding.
     
    Unique:
     Yes
     
    Maximum length
     
    255
     
    Required:
     Yes
     
    Description
     
    The description of the field you are adding.
     
    Maximum length:
     255
     
    Required:
     No
    Form
    Defines the custom field type (Applications or APIs). Do 
    one
     of the following:
    • To add a custom API field to the API wizards, select 
      APIs
      .
    • To add a custom application field to the Add and Edit Application pages, select 
      Applications
      .
     
    Input Type
     
    Defines the input type.
     
    Options:
     Text or Single-Select Dropdown
     
    Required:
     Yes
     
    Options
     
    (If you clicked 
    Single-Select Dropdown
     as the input type) Add one or more options. Remove any blank options. You can drag the options to reorder them.
     
    Required:
     Yes
     
    State
     
    Defines the state of the custom field.
     
    Values:
     Enabled and Disabled
     
    Default:
     Disabled
     
    Required:
     Yes
     
    Required Field
     
    To define the custom field as an optional field, select 
    No
    .
     
    Required:
     Yes
     If you are adding an optional custom application field, add an option such as "None". API developers who choose not to use this custom application field have the option of selecting the "None" option. Ensure that the API Gateway policy processes the "None" option appropriately.
The custom field appears on the 
Custom Fields
 page in alphabetical order.
Edit Custom Fields
  1. Select 
    Administration
    Custom Fields
    .
  2. Select 
    Edit 
    next to the custom field you want to edit.
    The 
    Edit Custom Field
     page opens.
  3. Edit the custom field.
    You cannot change the value for the 
    Form
     or the 
    Input Type
     fields.
  4. Select 
    Save
    .
Your changes to the custom field are saved.
Delete Custom Fields
Prerequisite: 
The custom field is disabled.
  1. Select 
    Administration
    Custom Fields
    .
  2. Select 
    Delete
     next to the custom field that you want to edit, and then select 
    Save
    .
The custom field is deleted.