Part 2: Configuration management

Content

Introduction

The REST management interface offers end-to-end configuration management capabilities in firmware release 7.2.0.0 of the IBM DataPower Gateway Appliance. You can retrieve and view existing configurations, perform updates on existing configurations, create configurations, and delete configurations. In Part 2 of this series, you learn about requests to retrieve, modify, and delete existing configurations. You also learn how to compose request payloads to create configurations. For information about other request types, such as status monitoring, file and directory management, and appliance operations, see the other parts in this series.

Retrieving existing configurations

In this section, you retrieve configurations of objects that are on the appliance.

Identify the object class

To begin retrieving existing configurations from the appliance, you first identify the object class of interest. To identify the required class name, access the root Uniform Resource Identifier (URI) of the REST management interface, as the following request shows, to identify the configuration root URI:

 GET https://dphost.com:5554/mgmt/

In the received response, as shown in Listing 1, you can identify the configuration root URI as /mgmt/config/.

 {   "_links": {     "self": {       "href": "/mgmt/"     },     "config": {       "href": "/mgmt/config/"     },     "domains": {       "href": "/mgmt/domains/config/"     },     "status": {       "href": "/mgmt/status/"     },     "actionqueue": {       "href": "/mgmt/actionqueue/"     },     "filestore": {       "href": "/mgmt/filestore/"     },     "metadata": {       "href": "/mgmt/metadata/"     },     "types": {       "href": "/mgmt/types/"     }   } }

Access the configuration root URI, /mgmt/config/, to retrieve a list of all available object classes on the appliance, as the following request shows:

 GET https://dphost.com:5554/mgmt/config/

To identify the exact formatting of the class name, search the received response payload, which is partially shown in Listing 2.

 {   "_links": {     "self": {       "href": "/mgmt/config/"     }   },   "AAAPolicy": {     "href": "/mgmt/config/{domain}/AAAPolicy"   },   "AccessControlList": {     "href": "/mgmt/config/{domain}/AccessControlList"   },   "AppSecurityPolicy": {     "href": "/mgmt/config/{domain}/AppSecurityPolicy"   },   "AS2ProxySourceProtocolHandler": {     "href": "/mgmt/config/{domain}/AS2ProxySourceProtocolHandler"   },   "AuditLog": {     "href": "/mgmt/config/{domain}/AuditLog"   },   "CertMonitor": {     "href": "/mgmt/config/{domain}/CertMonitor"   },   "CloudConnectorService": {     "href": "/mgmt/config/{domain}/CloudConnectorService"   },   ... }

As an alternative to identifying the formatting of the object class, examine the URI that is displayed in the WebGUI browser window when an object or object list is accessed.

After you determine the formatting of the class name, you can retrieve a list of existing objects for the target class. To retrieve the list, construct a URI of the form /mgmt/config/{domain}/{class_name}, replacing {domain} with the target domain and replacing {class_name} with the object class. This URI is shown in the following example with the target domain of my-testing-domain and the class name of HTTPSourceProtocolHandler:

 GET https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler

The response to a class listing request returns all objects of the class within the target domain. If no objects exist for the class, an informational message is returned, as shown in Listing 3.

 {   "_links": {     "self": {       "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler"     }   },   "result": "no configuration retrieved"   } }

If at least one object of a specific class exists within a domain, you can retrieve the configuration of that object. To retrieve the configuration, construct a URI of the form /mgmt/config/{domain}/{class_name}/{object_name}. In this form, replace {domain} with the target domain, {class_name} with the object class, and {object_name} with the specific object instance.

The following request shows this URI. Here, the target domain is my-testing-domain, the class name is HTTPSourceProtocolHandler, and the object name is test-HTTP-SPH.

 GET https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/ test-HTTP-SPH

The response to an object retrieval request returns the configuration of a specific object instance within the target domain, as shown in Listing 4.

 {   "_links": {     "self": {       "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/test-HTTP-SPH"     },     "doc": {       "href": "/mgmt/docs/config/HTTPSourceProtocolHandler"     }   },   "HTTPSourceProtocolHandler": {     "name": "test-HTTP-SPH",     "mAdminState": "enabled",     "LocalAddress": "0.0.0.0",     "LocalPort": 8001,     "HTTPVersion": "HTTP/1.1",     "AllowedFeatures": {       "HTTP-1.0": "on",       "HTTP-1.1": "on",       "POST": "on",       "GET": "off",       "PUT": "on",       "HEAD": "off",       "OPTIONS": "off",       "TRACE": "off",       "DELETE": "off",       "CONNECT": "off",       "CustomMethods": "off",       "QueryString": "on",       "FragmentIdentifiers": "on",       "DotDot": "off",       "CmdExe": "off"     },     "PersistentConnections": "on",     "MaxPersistentConnectionsReuse": 0,     "AllowCompression": "off",     "AllowWebSocketUpgrade": "off",     "WebSocketIdleTimeout": 0,     "MaxURLLen": 16384,     "MaxTotalHdrLen": 128000,     "MaxHdrCount": 0,     "MaxNameHdrLen": 0,     "MaxValueHdrLen": 0,     "MaxQueryStringLen": 0   } }

You can also retrieve the value of a specific property, instead of retrieving the object configuration in its entirety. To retrieve the value, construct a URI of the form: /mgmt/config/{domain}/{class_name}/{object_name}/{property_name}. In this URI, replace {domain} with the target domain, replace {class_name} with the object class, and replace {object_name} with the object instance. Also, replace {property_name} with the specific property name as it appears in the complete object configuration response in Listing 4.

The following request shows this URI. Here, the target domain is my-testing-domain, the class name is HTTPSourceProtocolHandler, the object name is test-HTTP-SPH, and the property name is LocalPort.

 GET https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/ test-HTTP-SPH/LocalPort

The response to an object property retrieval request returns the value of the specific object property, as shown in Listing 5.

 {   "_links": {     "self": { "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/       test-HTTP-SPH/LocalPort"     },     "doc": {       "href": "/mgmt/docs/config/HTTPSourceProtocolHandler"     }   },   "LocalPort": 8003 }

In this section, you modify and delete the configurations of objects that are on the appliance.

To modify an existing property value, you overwrite the existing value with a payload that contains an updated value. To overwrite the value, retrieve the current property value. For examples that use the HTTPSourceProtocolHandler object, see the request and response in Retrieve the object-level configuration and in Retrieve the property-level configuration.

Next, examine the current property value to determine the change. After you identify the current change, modify the property payload that is received, as shown in Listing 5, to remove the _links{} stanza. Any properties that reference other configuration objects on the appliance must also remove the embedded href link. Listing 6 shows the result with the payload that contains an updated property value for LocalPort.

 {   "LocalPort": 8012 }

After the modified payload is composed, overwrite the existing property value by sending an HTTP PUT request as shown in the following example. Updating the configuration on the property level allows for updating one property value per request. To update multiple property values with a single request, an update on the object level is required.

 PUT https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/ test-HTTP-SPH/LocalPort 

After the target property is updated, a confirmation response is received as shown in Listing 7.

 {   "_links": {     "self": {       "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/                test-HTTP-SPH/LocalPort"     },     "doc": {       "href": "/mgmt/docs/config/HTTPSourceProtocolHandler"     }   },   "LocalPort": "property has been updated." }

To modify an existing object configuration, overwrite the existing configuration with an updated payload. To overwrite the configuration, retrieve the current configuration of the object to be modified. An example of this request is shown in the object retrieval request for an HTTPSourceProtocolHandler object in Retrieve the object-level configuration.

Then, examine the current configuration, as shown in Listing 4, to determine the configuration changes. After you identify the current changes, modify the payload received in Listing 4 to remove the _links{} stanza and all properties that should remain unchanged. Remove the embedded href link for any properties that reference other configuration objects on the appliance as shown in Listing 8. In this listing, the payload contains the updated property values for mAdminState, LocalAddress, LocalPort, and HTTPVersion.

 {   "HTTPSourceProtocolHandler": {     "name": "test-HTTP-SPH",     "mAdminState": "disabled",     "LocalAddress": "1.2.3.4",     "LocalPort": 8005,     "HTTPVersion": "HTTP/1.0"   } }

After the modified payload is composed, send an HTTP PUT request to overwrite the existing configuration:

 PUT https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/ test-HTTP-SPH

Updating the configuration on the object level allows for updating multiple property values with a single request. You can update an individual property value on the property level instead, as explained in Modify the property-level configuration.

After the target object instance is updated, you receive a confirmation response as shown in Listing 9.

 {   "_links": {     "self": {       "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/test-HTTP-SPH"     },     "doc": {       "href": "/mgmt/docs/config/HTTPSourceProtocolHandler"     },     "test-HTTP-SPH": "Configuration has been updated." }

Configuration deletion is supported only on the object level. The object DELETE request expects to receive no request payload. If a payload is supplied, the following request is triggered, reporting a failure:

 DELETE https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/ test-HTTP-SPH

After the deletion request is processed, you receive a confirmation response as shown in Listing 10.

 {   "_links": {     "self": {       "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/test-HTTP-SPH     },     "doc": {       "href": "/mgmt/docs/config/HTTPSourceProtocolHandler"     }   },   "HTTPSourceProtocolHandler": {     "value": "Configuration has been deleted."   } } 

Deletion of individual object properties is not supported. To remove an optional property or to reset a required property to its default value, delete and re-create the entire configuration object. Omit the values of specific properties from the request payload. List properties, or properties that contain multiple entries of the same type, are handled differently. List properties allow updates and do not require the entire object configuration to be deleted first. For more information, go to Modifying the list properties.

In this section, you create configuration objects on the appliance. You also compose valid request payloads and send requests to create objects.

To create an object configuration, create a valid payload that contains the new configuration. If you cannot create a valid payload by examining response payloads of the REST management interface for the same object class, as shown in the request in Retrieve the object-level configuration and in Listing 4, use another approach.

To begin constructing the payload, identify the structural description of the target object, that is, the object schema. You can retrieve this information from two sources: the metadata resource of the REST management interface and the appliance Service-Oriented Management Interface (SOMA) schema. You can choose which approach to use to construct a valid payload because you do not need to consult both sources.

To retrieve the object schema from the metadata resource of the REST management interface, access the metadata root URI of the REST management interface:

 GET https://dphost.com:5554/mgmt/metadata/

The response that is returned from the metadata root URI (see Listing 11) shows the options that are available for retrieving the configuration object schema within the object link: /mgmt/metadata/{domain}/{object_name}.

 {   "_links": {     "self": {       "href": "/mgmt/metadata/"     },     "object": {       "href": "/mgmt/metadata/{domain}/{object_name}"     },     "property": {       "href": "/mgmt/metadata/{domain}/{object_name}/{property_name}"     },     "operation": {       "href": "/mgmt/metadata/{domain}/operations/{operation_name}"     }   } }

To retrieve object metadata, enter the following request. Here, for {domain}, substitute my-testing-domain, and for {object_name}, substitute the HTTPSourceProtocolHandler object class.

 GET https://dphost.com:5554/mgmt/metadata/my-testing-domain/HTTPSourceProtocolHandler

The information retrieved from the metadata resource is the same, regardless of the {domain} identifier. The {domain} identifier is required to ensure that the user has access permissions to the target domain.

The response returned from the metadata request can be large, depending on the target object class. The relevant information for constructing a request payload is in the properties element of the response, as shown in Listing 12 for the HTTPSourceProtocolHandler class. This list includes all target object properties and information about minimum and maximum values, required properties, and default values.

 {   "_links": {     "self": {       "href": "/mgmt/metadata/my-testing-domain/HTTPSourceProtocolHandler"     },     "doc": {       "href": "/mgmt/docs/metadata/HTTPSourceProtocolHandler"     }   },   "object": {     "name": "HTTPSourceProtocolHandler",     "uri": "protocol/http",     "cli-alias": "source-http",     ...     "properties": {       "property": [         {           "name": "mAdminState",           "type": {             "href": "/mgmt/types/default/dmAdminState"           },           "cli-alias": "admin-state",           "default": "enabled",           ...         },         {           "name": "UserSummary",           "type": {             "href": "/mgmt/types/default/dmString"           },           "cli-alias": "summary",           ...         },         {           "name": "LocalAddress",           "type": {             "href": "/mgmt/types/default/dmLocalIPHostAddress"           },           "required": "true",           "cli-alias": "local-address",           "default": "0.0.0.0",           ...         },         {           "name": "LocalPort",           "type": {             "href": "/mgmt/types/default/dmIPPort"           },           "required": "true",           "cli-alias": "port",           "minimum": 1,           "maximum": "0xFFFF",           "default": 80,           ...         },         {           "name": "HTTPVersion",           "type": {             "href": "/mgmt/types/default/dmHTTPVersion"           },           "cli-alias": "http-client-version",           "default": "HTTP/1.1",           ...         },         ...       ]     }   } }

To supplement the information that is retrieved from the metadata resource of the REST management interface, you can examine the SOMA schema of the target object. The SOMA schema for all configuration objects is available on the appliance from the default domain inside the store:///xml-mgmt.xsd file. Searching for an object class results in a schema similar to the one in Listing 13 for an HTTPSourceProtocolHandler class. By examining the minOccurs and maxOccurs attributes, you can easily observe the relevant information to construct a request payload for the REST management interface. For example, you can see which properties are required.

 <xsd:complexType name="ConfigHTTPSourceProtocolHandler">   <xsd:complexContent>     <xsd:extension base="tns:ConfigSourceProtocolHandler">       <xsd:choice maxOccurs="unbounded">         <xsd:element name="UserSummary" minOccurs="0" maxOccurs="1">           <xsd:simpleType>             <xsd:union memberTypes="tns:dmString tns:dmEmptyElement" />           </xsd:simpleType>         </xsd:element>         <xsd:element name="LocalAddress" minOccurs="1" maxOccurs="1">           <xsd:simpleType>             <xsd:union memberTypes="tns:dmLocalIPHostAddress tns:dmEmptyElement" />           </xsd:simpleType>         </xsd:element>         <xsd:element name="LocalPort" minOccurs="1" maxOccurs="1">           <xsd:simpleType>             <xsd:union memberTypes="tns:dmIPPort tns:dmEmptyElement" />           </xsd:simpleType>         </xsd:element>         <xsd:element name="HTTPVersion" minOccurs="0" maxOccurs="1">           <xsd:simpleType>             <xsd:union memberTypes="tns:dmHTTPVersion tns:dmEmptyElement" />           </xsd:simpleType>         </xsd:element>          ...       </xsd:choice>       ...     </xsd:extension>   </xsd:complexContent> </xsd:complexType>

By relying on the metadata resource of the REST management interface and on the appliance SOMA schema, you can identify the properties that are required to create the target object. You can also identify the property names to use in the payload. By using this information, a proper JSON request payload is structured as shown in Listing 14.

 {   "{object_class_name}": {     "name": "{object_name}",     "{property1_name}": "{property1_value}",     "{property2_name}": "{property2_value}",     "{property3_name}": "{property3_value}",     "{property4_name}": "{property4_value}"     ...   } }

When you substitute the {object_class_name}, {object_name}, and all required properties and their values, a valid JSON request payload for the REST management interface is created. Listing 15 shows a valid payload to create an HTTPSourceProtocolHandler object, where the property values are set for mAdminState, LocalAddress, LocalPort, and HTTPVersion.

 {   "HTTPSourceProtocolHandler": {     "name": "test-HTTP-SPH",     "mAdminState": "enabled",     "LocalAddress": "0.0.0.0",     "LocalPort": 8001,     "HTTPVersion": "HTTP/1.1"   } }

You can choose from two approaches to create a configuration object. Both approaches achieve the same result, but target a different URI. The first approach uses an HTTP POST request, and the second uses an HTTP PUT request. Use the POST request to create objects because a POST request results in failure if an object with the same name exists in the target domain. This approach prevents you from accidentally overwriting an existing object configuration. However, you can create an object configuration by using a PUT request. Issuing a PUT request on an existing object configuration overwrites the configuration with the values in the request payload.

To create a configuration object with a POST request, construct a URI as follows and use an appropriate substitute for {domain_name} and {class_name}:

 POST https://dphost.com:5554/mgmt/config/{domain_name}/{class_name}

To create a configuration object with a PUT request, construct a URI as shown in the following request. Use an appropriate substitute for {domain_name}, {class_name}, and {object_name}. The {object_name} in the URI and the request payload must match. Otherwise, an error results.

 PUT https://dphost.com:5554/mgmt/config/{domain_name}/{class_name}/{object_name}

After you construct the request payload and the target URI, create an object configuration by sending a POST request or PUT request. The following example shows how to create an HTTPSourceProtocolHandler object with a POST request:

 POST https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler

The following example shows how to create the same object with a PUT request:

 PUT https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/ test-HTTP-SPH 

For both request types, the {domain_name}, {class_name}, and {object_name} values were substituted with the same values shown in Compose the valid request URI.

Both the POST and PUT requests return the same response after the object is successfully created, as shown in Listing 16.

 {   "result": "",   "_links": {     "self": {       "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler"     },     "doc": {       "href": "/mgmt/docs/config/HTTPSourceProtocolHandler"     }   },   "test-HTTP-SPH": "Configuration has been created." }

The next POST and PUT requests that are sent to the same target URI generate different responses. Subsequent POST requests to existing configuration objects result in an error, as shown in Listing 17.

 {   "_links": {     "self": {       "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler"     }   },   "error": "Resource already exists." }

The next PUT requests to an existing configuration object result in overwriting the object with the information in the incoming payload, as shown in Listing 18.

 {   "_links": {     "self": {       "href": "/mgmt/config/my-testing-domain/ 		    HTTPSourceProtocolHandler/test-HTTP-SPH"     },     "doc": {       "href": "/mgmt/docs/config/HTTPSourceProtocolHandler"   },   "test-HTTP-SPH": "Configuration has been updated." }

In the context of configuration management, list properties need special consideration. A property is a list if it contains multiple items of the same type. For example, a deployment policy object can contain three list properties: accepted configuration, filtered configuration, and modified configuration. List properties, similar to other properties, allow the HTTP GET and PUT methods for configuration retrieval and updates. The following request is for list property retrieval of a deployment policy object:

 GET https://dphost.com:5554/mgmt/config/default/ConfigDeploymentPolicy/test/AcceptedConfig 

As shown in Listing 19, the AcceptedConfig property contains four entries.

 {   "_links": {     "self": {    	"href": "/mgmt/config/default/ConfigDeploymentPolicy/test/AcceptedConfig"     },     "doc": {       "href": "/mgmt/docs/config/ConfigDeploymentPolicy"     }   },   "AcceptedConfig": [     "*/*/config/deployment-policy-variables?Name=pdp-params_1",     "*/*/config/deployment?Name=pdp-dp_1",     "*/*/config/pattern?Name=.*",     "*/*/services/sslforwarder?Name=SSLProxyService_test"   ] } 

List properties also allow the POST and DELETE HTTP methods, which is not true for other property types. For more information about the semantics of the POST and DELETE methods on list properties, see the following sections.

Append additional values to a list property with a POST request, supplying the additional configuration entries within the associated payload.

First, compose a request payload for the AcceptedConfig property of a deployment policy object that includes additional list entries, as shown in Listing 20.

 {    "AcceptedConfig": [       "value": "*/*/config/deployment-policy-variables?Name=pdp-params_2",       "value": "*/*/config/deployment?Name=pdp-dp_2"     ] }

Then, append the additional list entries (from Listing 20) to the AcceptedConfig property by sending a POST request:

 POST https://dphost.com:5554/mgmt/config/default/ConfigDeploymentPolicy/ test/AcceptedConfig 

After the request is completed, a confirmation response is returned as shown in Listing 21.

 {   "_links": {     "self": {       "href": "/mgmt/config/default/ConfigDeploymentPolicy/test/AcceptedConfig"     },     "doc": {       "href": "/mgmt/docs/config/ConfigDeploymentPolicy"     }   },   "AcceptedConfig": "property has been updated." }

Clear all current values from a list property by using a DELETE request. No request payload is expected for this request.

 DELETE https://dphost.com:5554/mgmt/config/default/ConfigDeploymentPolicy/ test/AcceptedConfig

After the request is completed, a confirmation response is returned as shown in Listing 22.

 {   "_links": {     "self": {       "href": "/mgmt/config/default/ 		   ConfigDeploymentPolicy/test/AcceptedConfig"     },     "doc": {       "href": "/mgmt/docs/config/ConfigDeploymentPolicy"     }   },   "AcceptedConfig": "property has been deleted." }

In the context of configuration management, bitmap properties also require special consideration. A property is a bitmap if it contains a collection of on/off or true/false values. For example, the FileMap property within a Domain object class contains multiple on/off settings:

 GET https://dphost.com:5554/mgmt/config/default/Domain/my-testing-domain

As shown in Listing 23, the FileMap property contains six entries with on/off settings.

 {   "_links": {     "self": {       "href": "/mgmt/config/default/Domain/my-testing-domain"     },     "doc": {       "href": "/mgmt/docs/config/Domain"     }   },   "Domain": {     "name": "my-testing-domain",     "mAdminState": "enabled",     "FileMap": {       "CopyFrom": "on",       "CopyTo": "on",       "Delete": "on",       "Display": "on",       "Exec": "on",       "Subdir": "on"     },     "ConfigMode": "local",     "ImportFormat": "ZIP",     "LocalIPRewrite": "on",     "MaxChkpoints": 3   } 

Property updates on bitmap properties have distinct behaviors:

• Updating only select bits within the bitmap property automatically sets all of the remaining unspecified bits to "off."
• If the bitmap property value in the request payload is present, but empty, all property bits are reset to their default values.
• If the object that contains the bitmap property is being updated and the bitmap property is omitted from the request payload, the bitmap property values remain unchanged.

Request and response examples for each behavior type are demonstrated in the following sections.

When a configuration object that contains the bitmap property is updated with a payload that contains an incomplete specification of the bitmap, the bits that are omitted are automatically set to the "off" setting. Listing 24 demonstrates this concept by modifying the FileMap property of a Domain object class with a payload that contains only the Exec bit of the FileMap property.

 {   "Domain": {     "name": "my-testing-domain",     "mAdminState": "enabled",     "FileMap": {       "Exec": "off"     },     "ConfigMode": "local",     "ImportFormat": "XML",     "LocalIPRewrite": "off",     "MaxChkpoints": 5   } } 

You send the object update request:

PUT https://dphost.com:5554/mgmt/config/default/Domain/my-testing-domain

The object configuration in Listing 25 shows the results, where the omitted entries are set to "off."

 {   "_links": {     "self": {       "href": "/mgmt/config/default/Domain/my-testing-domain"     },     "doc": {       "href": "/mgmt/docs/config/Domain"     }   },   "Domain": {     "name": "my-testing-domain",     "mAdminState": "enabled",     "FileMap": {       "CopyFrom": "off",       "CopyTo": "off",       "Delete": "off",       "Display": "off",       "Exec": "off",       "Subdir": "off"     },     "ConfigMode": "local",     "ImportFormat": "XML",     "LocalIPRewrite": "off",     "MaxChkpoints": 5   } }

When a configuration object that contains the bitmap property is updated with a payload that contains an empty bitmap, all bits are automatically reset to their default values. Listing 26 demonstrates this concept. In this listing, the FileMap property of a Domain object class is modified with a payload that contains an empty FileMap property. The default value of bits in the FileMap property is "on."

 {   "Domain": {     "name": "my-testing-domain",     "mAdminState": "enabled",     "FileMap": {     },     "ConfigMode": "local",     "ImportFormat": "ZIP",     "LocalIPRewrite": "on",     "MaxChkpoints": 3   } }

Sending the object update request, as shown in Set the partial bitmap property, results in the object configuration in Listing 27, where all the bitmap entries are reset to their default value of "on."

 {   "_links": {     "self": {       "href": "/mgmt/config/default/Domain/my-testing-domain"     },     "doc": {       "href": "/mgmt/docs/config/Domain"     }   },   "Domain": {     "name": "my-testing-domain",     "mAdminState": "enabled",     "FileMap": {       "CopyFrom": "on",       "CopyTo": "on",       "Delete": "on",       "Display": "on",       "Exec": "on",       "Subdir": "on"     },     "ConfigMode": "local",     "ImportFormat": "ZIP",     "LocalIPRewrite": "on",     "MaxChkpoints": 3   }

When a configuration object that contains the bitmap property is updated with a payload that omits the bitmap property, all the bits remain unchanged. Listing 28 demonstrates this concept, by modifying the Domain object class with a payload that entirely omits the FileMap property.

 {   "Domain": {     "name": "my-testing-domain",     "mAdminState": "disabled",     "ConfigMode": "local",     "ImportFormat": "XML",     "LocalIPRewrite": "on",     "MaxChkpoints": 5   } }

Sending the object update request, as shown in Set the partial bitmap property, results in the object configuration in Listing 29. Here, the bitmap entries remain unchanged from the last update, and the values of the other properties are updated with values in the payload.

 {   "_links": {     "self": {       "href": "/mgmt/config/default/Domain/my-testing-domain"     },     "doc": {       "href": "/mgmt/docs/config/Domain"     }   },   "Domain": {     "name": "my-testing-domain",     "mAdminState": "disabled",     "FileMap": {       "CopyFrom": "on",       "CopyTo": "on",       "Delete": "on",       "Display": "on",       "Exec": "on",       "Subdir": "on"     },     "ConfigMode": "local",     "ImportFormat": "XML",     "LocalIPRewrite": "on",     "MaxChkpoints": 5   } }

Conclusion

In this tutorial, you learned about configuration management through the REST management interface for IBM DataPower Gateway appliances. You learned how to retrieve, modify, and delete existing configurations on the appliance, and how to compose valid request payloads to create configurations. You also learned about the behaviors of list properties and bitmap properties of configuration objects. As you continue in this tutorial series, Part 3 explains file and directory management on the DataPower Gateway Appliance.

Resources

See the other parts in this series:

• REST management interface and IBM DataPower Gateway, Part 1: Introduction to the interface and status monitoring
• REST management interface and IBM DataPower Gateway, Part 2: Configuration management
• REST management interface and IBM DataPower Gateway, Part 3: File and directory management
• REST management interface and IBM DataPower Gateway, Part 4: Triggering appliance operations

The following links are helpful when reading this article:

• To get started with the REST management interface, see Enabling the REST management interface.
• For everything related to the REST management interface, see REST management interface.
• For example requests and responses from the REST management interface, see Samples that use the REST management interface.
• For DataPower SOA Appliances 7.2.0 documentation, see the IBM Knowledge Center.
• For DataPower tutorials in the developerWorks WebSphere zone, see the Technical Library.
• For the latest news and information, see the IBM developerWorks WebSphere zone.