Andergrove Software

IBM DataPower Gateway - Management APIs

• 12 min read

IBM DataPower Gateway is an integration platform used as API middleware for protocols such as SOAP and REST. It’s commonly used in large organisations such as banks and Government departments, because of it’s performance and security qualities. Though it has been on the market for many years - it has a relatively powerful management API for creating, retrieving and updating pretty much as aspect of it’s configuration.

Sadly, the documentation for this interface is not very good. Let’s take a look at how it works.

Let’s go over a few things real quick:

  • This interface takes the form of a REST API and a SOAP API. In this article, we focus on the REST API, but note that the SOAP API has basically the same functionally (possibly more; the SOAP API pre-dates the REST API). In fact, the REST API’s field names and structure basically matches the SOAP API very closely (perhaps even 100%).

  • We will have HTTP methods for configuring most aspects of the DataPower, from the server configuration - things like NTP, DNS, network config and so on - to the application configuration, which application APIs to expose, which javascript modules to invoke when we get a request, and so on.

  • The REST API requires the base URL to the server we are to configure, plus a user with access to run the methods.

  • When we create objects using the REST API and then save them, they are persisteted as ‘configuration objects’ - this is the .cfg file in the /config folder that you’ll see. That .cfg file format is text - some weird, proprietary format. We don’t want to deal with objects in that format, though we could add globs of text and acheieve the same outcome. Rather, we want to use a nice REST API to create our objects, and only deal with the text .cfg format when we need to - like when working with kubernetes.

Now that that’s out of the way, let’s jump into the detail.

Note - We will include an Insonia test export so you can play with some examples interactively. You can grab it here.

Test Setup

In order to demo the REST API and play with it, we will be using curl and a docker instance of the free DataPower developer image. See Setting Up DataPower Docker for Development for more information about how to do that.

We are using version 10.0.5.1 here - so if you’re reading this in year 2025 and there are new objects, that’s why. I wouldn’t expect the structure of the APIs to change in the future, not in a backwards incompatible way.

Don’t forget to enable the REST Management Interface which is disabled by default and uses port 5554 per standard. You can do this easily through the UI or CLI (but obviously not the REST API 😀). Also, the REST API will use a self-signed cert by default - so update or trust that, or use the “-k” option with curl.

Finally, most operations will require authentication. This takes the form of a Basic auth credential. For a docker instance with default user:password of admin:admin, that HTTP header would look like: Authorization: Basic YWRtaW46YWRtaW4=

Mgmt API Overview

We run through the REST API here interactively with curl. Note that the REST API makes proper use of HTTP verbs - so a GET will be a READ, POST will be a new object, PUT will be a update-if-not-existing or create and DELETE will delete.

curl -k -u "admin:admin" https://localhost:5554 
{
    "_links":{
            "self":{"href":"/"},
            "mgmt":{"href":"/mgmt/"}
}}

This is the basic structure of each response - a _links field that shows where we are and where we can go, and then more fields based on what operation we performed. The trailing slash is important! Let’s try /mgmt:

curl -k -u "admin:admin"  https://localhost:5554/mgmt/
{
    "_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/"}
}}

That’s a lot of stuff. Let’s walk through what they are:

config - This resource lists out the various objects types that we can mutate - XMLManager, MgmtInterface, CryptoCertificate and so on

domains - This resource lists the domains that exist on our server - initially, default

status - This resource lists ‘status’ objects, which is the runtime status of things like MQ connections, power supplies (for hardware devices), TCP connections, and so on

actionqueue- This resource lists ‘actions’ that are running, and we can run, on our DataPower server; things like saving the configuration (SaveConfig), flushing document caches (FlushDocumentCache), and refreshing WSDLs (RefreshWSDL)

filestore - This resource gives us access to the DataPower filesystem, for reading, writing, updating and deleting files

metadata - A very important endpoint that gives us a machine (and semi-human) readable description of what the different object types are for, what their properties do and what values they can take on

types - Also a metadata endpoint, this URL tells us about the datatypes that we will see appear throughout the REST API - what their fields and allowed values are, and so on

Okay, that’s a quick overview of the API and what it’s capable of (basically - anything you can do through the UI or SOMA interface). If you’re like me, that probably isn’t clicking and you want to see some concrete details. Let’s do just that!

REST MGMT API by Example

  • List all domains 
curl --request GET 
  --url https://localhost:5554/mgmt/domains/config/ 
  --header 'Authorization: Basic YWRtaW46YWRtaW4=
{
	"_links": {
		"self": {
			"href": "/mgmt/domains/config/"
		},
		"doc": {
			"href": "/mgmt/docs/config/domains"
		}
	},
	"domain": [
		{
			"name": "default",
			"href": "/mgmt/config/default/Domain/default"
		},
		{
			"name": "testDomain",
			"href": "/mgmt/config/default/Domain/testDomain"
		}
	]
}
  • Create a new HTTP handler with all fields explicitly set
curl --request POST 
  --url https://localhost:5554/mgmt/config/default/HTTPSourceProtocolHandler 
  --header 'Authorization: Basic YWRtaW46YWRtaW4=' 
  --header 'Content-Type: application/json' 
  --data '{
	"HTTPSourceProtocolHandler" : {
		"name": "blah3",
		"mAdminState": "enabled",
		"LocalAddress": "0.0.0.0",
		"LocalPort": 8080,
		"HTTPVersion": "HTTP/1.1",
		"AllowedFeatures": {
			"HTTP-1.0": "on",
			"HTTP-1.1": "on",
			"HTTP-2.0": "off",
			"POST": "on",
			"GET": "off",
			"PUT": "on",
			"PATCH": "off",
			"HEAD": "off",
			"OPTIONS": "off",
			"TRACE": "off",
			"DELETE": "off",
			"CONNECT": "off",
			"CustomMethods": "off",
			"QueryString": "on",
			"FragmentIdentifiers": "on",
			"DotDot": "off",
			"DotDotInPath": "off",
			"DotDotInQueryString": "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,
		"CredentialCharset": "protocol",
		"HTTP2MaxStreams": 100,
		"HTTP2MaxFrameSize": 16384,
		"HTTP2StreamHeader": "off",
		"ChunkedEncoding": "on",
		"HeaderTimeout": 30000
	}
}'
{
	"_links": {
		"self": {
			"href": "/mgmt/config/default/HTTPSourceProtocolHandler"
		},
		"doc": {
			"href": "/mgmt/docs/config/HTTPSourceProtocolHandler"
		},
		"location": {
			"href": "/mgmt/config/default/HTTPSourceProtocolHandler/blah3"
		}
	},
	"blah3": "Configuration was created."
}
  • Save application configuration (like hitting Save Config in the UI):
curl --request POST 
  --url https://localhost:5554/mgmt/actionqueue/default 
  --header 'Authorization: Basic YWRtaW46YWRtaW4=' 
  --header 'Content-Type: application/json' 
  --data '{
  "SaveConfig" : "0"
}'
{
	"_links": {
		"self": {
			"href": "/mgmt/actionqueue/default"
		},
		"doc": {
			"href": "/mgmt/docs/actionqueue"
		}
	},
	"SaveConfig": "Operation completed.",
	"script-log": ""
}
  • Get a specific application object - here, a HTTP handler
curl --request GET 
  --url https://localhost:5554/mgmt/config/default/HTTPSourceProtocolHandler 
  --header 'Authorization: Basic YWRtaW46YWRtaW4='
{
	"_links": {
		"self": {
			"href": "/mgmt/config/default/HTTPSourceProtocolHandler"
		},
		"doc": {
			"href": "/mgmt/docs/config/HTTPSourceProtocolHandler"
		}
	},
	"HTTPSourceProtocolHandler": {
		"name": "blah",
		"_links": {
			"self": {
				"href": "/mgmt/config/default/HTTPSourceProtocolHandler/blah"
			},
			"doc": {
				"href": "/mgmt/docs/config/HTTPSourceProtocolHandler"
			}
		},
		"mAdminState": "enabled",
		"LocalAddress": "0.0.0.0",
		"LocalPort": 8080,
		"HTTPVersion": "HTTP/1.1",
		"AllowedFeatures": {
			"HTTP-1.0": "on",
			"HTTP-1.1": "on",
			"HTTP-2.0": "off",
			"POST": "on",
			"GET": "off",
			"PUT": "on",
			"PATCH": "off",
			"HEAD": "off",
			"OPTIONS": "off",
			"TRACE": "off",
			"DELETE": "off",
			"CONNECT": "off",
			"CustomMethods": "off",
			"QueryString": "on",
			"FragmentIdentifiers": "on",
			"DotDot": "off",
			"DotDotInPath": "off",
			"DotDotInQueryString": "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,
		"CredentialCharset": "protocol",
		"HTTP2MaxStreams": 100,
		"HTTP2MaxFrameSize": 16384,
		"HTTP2StreamHeader": "off",
		"ChunkedEncoding": "on",
		"HeaderTimeout": 30000
	}
}
  • Update a specific (previously created) HTTP handler’s admin state from disabled to enabled

Note - You can also specify all fields that retain the same value, if you’re automating it - or have lost track of what the old state is.

curl --request PUT 
  --url https://localhost:5554/mgmt/config/default/HTTPSourceProtocolHandler/blah3 
  --header 'Authorization: Basic YWRtaW46YWRtaW4=' 
  --header 'Content-Type: application/json' 
  --data '{
	"HTTPSourceProtocolHandler" : {
		"name": "blah3",
		"mAdminState": "enabled"
	}
}'
{
	"_links": {
		"self": {
			"href": "/mgmt/config/default/HTTPSourceProtocolHandler/blah3"
		},
		"doc": {
			"href": "/mgmt/docs/config/HTTPSourceProtocolHandler"
		}
	},
	"blah3": "Configuration was updated."
}
Andergrove Software

This is the Andergrove Software blog, in which we write about interesting software challenges we encounter. If you like what we write, consider working with us - check out the <a href="https://andergrove.com/services/" class="font-medium text-blue-600 dark:text-blue-500 hover:underline">services we provide</a>.