Wednesday, August 7, 2019

Midsummer Thoughts on the Fun of Coding, Obvious Secrets, and Whether Plumbers Plumb on Vacation

A recent documentary shown on american television ( chronicled the 
life of Ben Hogan, the greatest golfer of the 1950’s. Hogan is a fascinating person, 
not only for his success as a professional athlete, but his overcoming personal tragedy. His father 
committed suicide when he was a child. Years later, as an adult, when he reached the pinnacle of 
his sport, he was nearly killed in a head-on collision between the car he was driving and a bus. 
After multiple surgeries and months of recovery, he was once again able to become the top athlete 
in the world for his sport. He became so proficient, in fact, that he was rumored to have found “the secret.” 

Every athlete searches for the secret to better performance, but in reality, “the secret” usually 
comes down to a combination of talent, hard work, and perseverance. In Hogan’s case, it was 
definitely a combination of the second and third of these factors. To a great degree, he invented 
modern practice where repetition in practice was the key to success performance under pressure. 
It has been an obsession lasting decades to try to discover Hogan’s secret. The answer may have been 
obvious. If he had a true secret, it was hard work coupled with the fact that he actually enjoyed 
practice. It was never work or drudgery to him. For him, practice was actually fun.

But, what does this have to do with software engineering? Fast forward to this week. 

We had taken the family to the beach for a week of vacation. After returning from a day at the beach, 
everyone in the family was relaxing their own way. My wife poured herself a glass of white wine and 
became engrossed in FaceBook.Grandma tuned the TV to the Golf Channel and complained 
about the beach traffic to anyone who would listen.The kids tortured each other over a game of ping-pong And me? I put my feet up and was unwinding by downloading an open source project that I had just 
 discovered on github.
Later on, my daughter remarked to me, in her usual subtle manner, “Geesh dad, you’re always on the 
computer. Don’t you ever want a break? Do you think that plumbers do plumbing when they are on 
vacation?” She does have a point. For a lot of people after working a full day, the last thing that they 
want to do is to look at or work on anything job related in the evening, especially when they are on 
vacation. I tend to doubt that very many plumbers do a lot of plumbing when they are on vacation. 

But, software engineers are different.

What is is about software and software engineering that makes us always wanting more? One reason 
may be that rapid changes in technology are interesting and frequently exciting. Another reason might be 
that given the rapid rate of change it’s important for your career to stay current with the latest 

These are all valid reasons, but I think that the "secret" for us, just as it was for Hogan and his practicing, 
is obvious, that we actually enjoy reading and writing code. 

In other words, for us, it’s fun!

Part of the fun comes from the nature of software itself. When you're working with physical media 
such as with steel, or concrete, or beach sand, the limitations of what you can do are based on 
physical limitations of that media and the physical environment. In contrast, with software, you can 
face limitations of memory or CPU speed or environment, but you are primarily only limited by your 
imagination. This is what makes software engineering so rewarding, and so much fun. You are 
basically building virtual structures out of ideas. And, unlike physical media, you can easily tear down, 
redesign, and rebuild structures in software. 

Wishing everyone a fun end of the summer!

Sunday, December 23, 2018

Divided by (the lack of) a Common Language?

”Why are you bothering with tests that don’t work?”

I remember the incident distinctly, even though it took place several years ago at a company that no longer exists, while my team was building and testing a long forgotten product. I was reviewing a software test plan with a development team colleague as I wanted his input on the risks associated with a new feature. I described the functional tests that wanted to build for the feature, and then mentioned that we would in parallel be updating the product’s non-functional tests (such as performance and security tests) to take into account the new operation of the new feature. He looked confused and asked me,”Why are you bothering with tests that don’t work?” His question caught me off guard and when I asked him to explain, he said, “You’re talking about tests that won’t function. Why are you wasting time on those tests? They’re broken, right?”

At that point, I thought of George Bernard Shaw’s famous quote about the British and Americans being two peoples divided by a common language. In this case, however, the problem was two groups of people being divided by the lack of a common language. That being, the language of software testing.

Historically, Development and QE teams have been kept separate. The separation was based on the belief that the only way to have effective and unbiased testing of a product was through having an independent testing team. One of the rationales for this separation is that testing always includes an element of “creative destruction” and that is difficult for people to act in a destructive manner toward their own work.

In an agile development model, this artificial separation is done away with. The walls that divided development and test engineers are torn away broken and they work together as members of the same team, where the quality of the product created is owned by every member of the team. The transition to this model from a traditional waterfall development model can, however, be difficult. The problem is that people without a QE/test background will be asked to build and run tests when they may lack hands in experience in test development beyond building unit tests. The “test guys” (that is, the QE/test engineers) can help by providing guidance and coaching, but but that coaching can difficult because people new to testing will not have a frame of reference to build upon.

A Shared Language - And Two “Good Reads” for Anyone Building Software Tests

When you work in a technical field it’s easy to become totally absorbed in the technology and forget the importance of human communication and community. What makes a community? Shared values, shared goals, shared experiences, shared literature, and a shared language for software testing.

It’s winter here in Boston, which makes it a great time to sit down by the fire, or at least a video of a fire, and do some reading. There are a couple of resources that anyone new to testing should read:

The year 2019, marks the 40th anniversary of the original release of Glenford Myers’ book, The Art of Software Testing. It’s still my favorite software testing book. In this little book, Myers provides a practical, and very readable description of methodologies for software test design. Equivalence partitioning, boundary value analysis, it’s all there in The Art of Software Testing.

In its syllabus and glossary, just updated in 2018, the International Software Testing Qualifications Board (ISTQB, provides a detailed and systematic definition of software testing. Founded in 2002, the ISTQB has established standards and certifications for software testers. In their glossary and syllabus, the ISTQB painstakingly describes how to design, organize, execute, and report on the results of software testing.

Building effective software tests are not just for “the test guys” anymore. In an agile model, we all own and contribute to and execute tests to improve product quality. Doing some basic research by reading The Art of Software Testing and the ISTQB syllabus and glossary would make for a very useful New Years resolution for anyone wanting to learn learn the language of software testing and to create better tests. Happy 2019!

Sunday, August 14, 2016

Management tip - When the Pizza is Free, Answer the Phone

It all began with free pizza.

Pepperoni pizza.jpg
Public Domain,

Many jobs ago, when I was working for a company that coincidentally no longer exists, there was a monthly event that no one looked forward to; the monthly managers’ meeting.

My fellow managers were, as individuals, extremely pleasant and competent people, but when they got together, group paralysis seemed to set in as they became collectively incapable, or even afraid, of taking independent action.

I remember one meeting especially well as it taught me a valuable management and leadership lesson. It all involved free pizza. In an effort to improve both morale and attendance, it was decided that the monthly meetings would be scheduled during everyone’s lunch hour, and that a free pizza lunch would be provided.

The meeting started promptly at noon, and soon settled into a familiar pattern of discussing, delaying, denying, and deferring actions to be taken.

And then, the telephone in the conference room rang.

The conversation stopped. Everyone stared at the telephone as it continued to ring. What could this mean? Why would someone place a telephone call into a conference room? Were we being watched? The phone continued to ring. Everyone stared at the phone, trying to will the ringing to stop.

After a few rings, I answered the phone. “It’s the front desk. The pizza is here.” Instantly, the tension was broken. Everyone started to breathe again.

But, after a few seconds, everyone froze again. Glances of uncertainty were exchanged. Everyone in the room shared the same thought, “What should we do now?” After a few more seconds of deafening silence, I stood up and addressed the team, as they sat frozen in their chairs and said, “I’ll go downstairs and get the pizza.”

OK, I may be exaggerating for dramatic effect, but I really did see this happen. It’s easy to dismiss this silly little story as a silly little story, but I think that there’s more to it. Individuals, small groups, and large institutions often create their own inertia. It’s the responsibility of team leaders and managers to recognize when forward progress is stalled and change the team’s inertia by removing obstacles. This may require shifting resources from one task to another, or it may require adjusting the relative priorities of task assignments, or it may require simply answering the phone and picking up free pizzas.

Friday, May 6, 2016

The JBoss apiman Crash Course Guide is published!

Just published a brief and easy to follow "crash course" guide to JBoss apiman. Hoping that this will help lots more people get started with API Management with JBoss apiman...

Friday, April 8, 2016

Introduction to User Roles in apiman

In this post, we’ll examine apiman user roles. In the apiman data model, all data elements exist in the context of the organization. The same holds true for user memberships as users can be members of multiple organizations. Permissions in apiman are role based. The actions that a user is able to perform are dependent on the roles to which the user is assigned when a user is added as a member of an organization.

Let’s start by looking at the roles that are preconfigured in apiman.

Understanding OOTB apiman user roles

In apiman, each role defines a set of permissions granted by that role. When a user is made a member of an organization, that user must be assigned to a role. A role definition consists of a name and description, and, most importantly, a set of permissions that govern the user’s ability to view, edit, and administer the organization itself, as well as the organization’s plans, APIs, and applications.

Roles are managed in the Roles section of the apiman System Administration form in the Management UI.

Apiman is preconfigured with the following roles:

  • Organization Owner
  • API Developer
  • Client App Developer

These role names are self-explanatory. For example, a user assigned the Application Developer role is able to manage the organization’s applications but is blocked from managing its APIs or plans.

The full set of permissions provided in apiman by these preconfigured roles are:

Preconfigured apiman Role
Who Should be Assigned this Role
Permissions Granted to this Role
Client App Developer
Users responsible for creating and managing client apps.
  • Client App View
  • Client App Edit
  • Client App Admin
Organization Owner
Automatically granted to the user who creates an Organization.
All permissions:
  • Client App View
  • Client App Edit
  • Client App Admin
  • Plan View
  • Plan Edit
  • Plan Admin
  • API View
  • API Edit
  • API Admin
  • Organization View
  • Organization Edit
  • Organization Admin
API Developer
Users responsible for creating and managing APIs.
  • Plan View
  • Plan Edit
  • Plan Admin
  • API View
  • API Edit
  • API Admin

Organization owners can assign roles to users through the “Manage Members” form in the apiman Management UI. Each user must be assigned at least one role, but users can also be assigned multiple roles.

We’ll walk through an example of assigning a role to a user in a moment.

While apiman admin users can also modify the permissions as defined for these preconfigured roles, it can be easier to create new custom roles. We will also walk through an example of creating a new user role later in this post.

Assigning/Revoking Roles for Organization Users

It’s worth repeating that all data elements in apiman exist in the context of an organization.  As a result, it is important to understand that users can only manage these elements if they have the appropriate role for the organization in which the elements exist.  Therefore, a user must be granted membership in an organization.

It’s not possible for users to assign themselves roles. Roles must be assigned to a user by an organization owner. Assigning a role to a user is a straightforward task for an organization owner.

First, the organization must search for the user:


And then, the organization owner can select a role from the existing set of roles:

Revoking a role for a user is just as easy. The organization owner simply has to search for the user, and then deselect a role for the user.

The same approach for assigning/revoking a role for a user is followed for the standard roles that are preconfigured in apiman, and for custom roles that you create.

Creating a New User Role/Defining the Role Permissions

In addition to providing a set of preconfigured roles, apiman also provides a means for apiman admin users to create new roles where you can define a custom set of permissions for each role. Custom roles give you the ability to exercise fine-grained control over the set of permissions granted to users.

Let’s look at an example of a custom role.

Imagine a situation where you have API developer users and application developer users. These sets of users can rely on apiman’s preconfigured roles. Let’s also imagine that you have a third set of user. You want these users to have read access to APIs and applications so that they can participate in a review/approval process. However, you do not want to give these users write access. For example, suppose you have to find a job for a certain relative of yours. He may be a thoroughly competent person, but you’d feel better if he didn’t have write access to anything valuable. A read-only role for your brother in law would look something like this:


Once the “brother-in-law” role is created, you can assign it to other users in the same manner as any other role:


In Conclusion

A consistent pattern in apiman is a rich set of features provided OOTB, and a method for you to expand on these features by creating customizations. User roles enable you to assign users permissions based on the tasks that they perform. Apiman is preconfigured with a rich set of roles OOTB, and also enables you to create new, custom roles to handle additional types of users (even your brother-in-law).

Tuesday, February 23, 2016

Improvements to Plugin Management in JBoss apiman

Introduction - Policies - The Most Important Part of API Management

In API Management, policies are where the action is. It’s through the application of policies that an API Management system such as apiman performs API governance. All the subsystems in apiman, from the Management API UI to the API Gateway, exist for one ultimate goal; to ensure that API governance is achieved by the application of policies to API requests. In apiman, a policy is a rule, or set of rules that controls responses to API requests. There are multiple types of apiman policies. Some policies allow or block access to APIs based on the IP address of the client application, while others allow or restrict access to specific resources provided by an API, while still others enable you to control or “throttle” the rate at which requests made to an API.  

Apiman is preconfigured with a set of policies, and also enables you to create your own custom policies. This article describes the improvements introduced in apiman release 1.2.x that enable you to better manage your custom policy plugins.

Apiman Plugin Management Improvements - Extending Flexibility

Apiman is not only preconfigured with a rich set of policies that you can use, right out of the box, but, from its earliest releases, apiman has also included a mechanism that you can use to define your own custom policies through plugins.

Apiman release 1.2.x adds these new features that enable you to better manage your custom policy plugins:

  • Uninstalling Policies
  • Upgrading Policies
  • Automatically Reloading SNAPSHOT Version Policies

The best way to understand how these features work is to see them in action.

Uninstalling a Policy Plugin

Before we can uninstall a policy plugin, we have to install it.

Apiman is preconfigured with a core set of policy types that can handle many common situations:

  • Authorization - Access to API resources is controlled by user roles
  • BASIC Authentication - A username/password is required to access an API
  • Caching - Cache responses from a backend API
  • Ignored Resources - Paths to API resources that will not be accessible
  • IP Blacklist - Clients with specific IP address(es) will be blocked from accessing an API
  • IP Whitelist - Clients with specific IP address(es) will not be blocked from accessing an API (all IP addresses not listed will be blocked)
  • Limiting - Access to an API is limited by the number of requests in a defined time period (generally used to create a fine-grained limit)
  • Quota - Access to an API is limited by the number of requests in a defined time period (generally used to create a coarse-grained limit)
  • Transfer Quota - Similar to a Quota policy, but based on the number of bytes transferred, not the number of requests

These core policy types cannot be uninstalled.

Apiman is also includes second set of policy types which can be optionally installed as plugins:

  • CORS - This plugin implements CORS (Cross-origin resource sharing): A method of controlling access to resources outside of an originating domain.   
  • HTTP Security - Provides a policy which allows security-related HTTP headers to be set, which can help mitigate a range of common security vulnerabilities.     
  • JSONP - A plugin that contributes a policy that turns a standard RESTful endpoint into a JSONP compatible endpoint.     
  • Keycloak OAuth - This plugin offers an OAuth2 policy which leverages the Keycloak authentication platform as the identity and access provider.     
  • Log Headers - Offers a simple policy that allows request headers to be added or stripped from the HTTP request (outgoing) or HTTP response (incoming).     
  • XML<->JSON Transformation - This plugin provides a very simple policy which can transform the request and/or response payload between XML and JSON.    

The optional plugins are accessed in this administrative page in the apiman Management UI:
To install a policy plugin, click on “Install” - for example, to install the Log Headers Policy:
And, it’s installed!

OK, we installed the policy plugin. Now, let’s uninstall it!

Uninstalling a policy plugin is as simple as installing it. All you do is select the plugin from the “Manage Plugins” page in the Administrative UI:

There are a couple of caveats to keep in mind when you uninstall a policy plugin:

  • First, uninstalling the plugin removes it from the apiman Management UI, but it still remains in use for all APIs in which it was previously configured.
  • Second, if you want to completely remove the plugin from all APIs in which it was previously configured, you must manually click on each API, Plan, and Client App that uses the policy and remove it. Apiman does not include a single “kill” button to automatically remove all references to a policy.

Upgrading Policy Plugins

In addition to enabling you to create and install your own custom policies, apiman also provides a mechanism to upgrade to new versions of those policies. This is an especially useful feature as, over time, a policy may be upgraded to include bug fixes or new features.

The best way to illustrate how to upgrade a policy plugin is to follow the process step-by-step.

For this illustration, we’ll use one of the policy plugins provided in the official apiman plugins git repository ( as our custom plugin. Many of the plugins provided in this repository are also available set of “available plugins” packaged with apiman. We’ll use one of the plugins (“test-policy” - it’s a very simple policy that adds a header to the inbound http request) that is not already installed into apiman for this example.

(Note that in order to follow this example, you will have to have maven and git installed.)

To download the policy plugins, execute these commands:

cd apiman-plugins

Before we build the plugins, we have to make one small change. The plugins as downloaded are assigned version numbers that include a -“SNAPSHOT” suffix. We will want to remove that suffix for this example. (Sneak peek: We will restore the suffix later in this article as apiman includes a new feature where “SNAPSHOT” version plugins are automatically reloaded.)

To make these changes, edit these files, and change the version from “1.2.2-SNAPSHOT” to “1.2.2”:


Then, to build the plugins, and install them into your local maven repo (at runtime, the apiman API Gateway installs plugins from the local maven “.m2” repo directory), execute this command:

mvn install

OK, our policy plugin is built, let’s add it into the management UI.

As an administrative user, navigate to the “Manage Plugins” page in the Management UI and select the “Available Plugins” tab:

Then, click on the “Add Custom Plugin” button. The following dialog is displayed. Fill in the details for the “test-policy” plugin. (You can find all this information in the plugin’s “pom.xml” file.) apiman will use this information to locate the policy plugin in your local maven repo:

And, after you click on the “Add Plugin” button, the policy plugin is installed:


Notice that there are (2) buttons in the “Actions” column of the “Installed Plugins”  table. The button labeled with an “X” enables you to remove the plugin. The button labeled with an up-arrow enables you to upgrade the policy plugin.

In order for apiman to recognize that a plugin policy has been updated, the plugin version number must change. To change the version number of the test-policy plugin, edit these files, and change the version from “1.2.2” to “1.2.3”:


Then, to rebuild the plugins, and install them into your local maven repo, execute this command:

mvn clean install

After rebuilding the plugins, return to the apiman Management UI, and click on the plugin policy’s upgrade button. Enter the new plugin version number in the dialog that is displayed:


And, after you perform the upgrade by clicking on the “OK” button, the plugin is upgraded:


There are a few important things to keep in mind while upgrading policy plugins:

  • The upgraded version of a policy plugin replaces the previous version.
  • Plans, APIs, or Client Apps that had previously been configured with the old version of the plugin policy will continue to use that older version. They will not be automatically updated to use the upgraded version of the policy plugin.
  • New Plans, APIs, or Client Apps that are created after the policy plugin was upgraded will use the new/upgraded version.
  • If you want to upgrade existing Plans, APIs, or Client Apps to use an upgraded policy plugin, then you will have to manually remove the old policy plugin version and then add the new policy plugin version. The apiman project documentation recommends against doing this unless there is a bug fix or new feature added in a policy plugin upgrade.

Automatically Reloading SNAPSHOT Version Policies

The final new feature added to Plugin Management in apiman 1.2.x is the automatic reloading of SNAPSHOT version policy plugins.

When you are developing a custom policy plugin, you may have to uninstall and reinstall the plugin many times while it is being debugged. This can quickly become a time-consuming manual task. Apiman 1.2.x now makes it possible for you avoid this manual installing/re-installing.

As we’ve just seen, the apiman API Gateway installs policy plugins from your local maven repo. To be more efficient, the API Gateway caches plugins the first time that they are used. If, however, a plugin’s version ends with a “-SNAPSHOT” suffix, then the API Gateway will reload it every time the plugin is used.

So, by including a “-SNAPSHOT” suffix in your custom policy plugin’s version, you can iterate through changes to the policy plugin  without having to manually uninstall and then install each new version of the plugin.

Let’s take a look at this in action.

Since we want to take advantage of the automatic reloading, we must restore the “-SNAPSHOT” suffix to the test-policy custom policy plugin. To make these changes, edit these files, and change the version from “1.2.3” to “1.2.2-SNAPSHOT”:


Then, to build the plugins, and install them into your local maven repo, execute this command:

mvn clean install

And then add the custom policy plugin in the Management UI:

And, here’s the installed plugin:


Before we can configure the custom policy plugin, we need an API. For this example, we’ll use our old friend, “apiman-echo.” You can download this API from this git repository:

The steps to build, deploy, and configure this API are available in the first article in this series:

We’ll use the postman web client to access the API. The first time that we access the API, we’ll see this response (note the text highlighted in green):

"method" : "GET",
"resource" : "/apiman-echo",
"uri" : "/apiman-echo",
"headers" : {
  "Accept" : "*/*",
  "Cache-Control" : "no-cache",
  "User-Agent" : "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.86 Safari/537.36",
  "Connection" : "keep-alive",
  "Test-Policy" : "true",
  "Postman-Token" : "8808bb68-1c1c-ef97-449d-ab60f620b0e5",
  "Host" : "localhost:8080",
  "Accept-Language" : "en-US,en;q=0.8",
  "Accept-Encoding" : "gzip, deflate, sdch"
"bodyLength" : null,
"bodySha1" : null

OK, now, let’s change the policy plugin. In this file: src/main/java/io/apiman/plugins/test_policy/

Change this line from this:
request.getHeaders().put("Test-Policy", "true");

To this:
request.getHeaders().put("Test-Policy", "quite true");

And then, rebuild the plugin with this command:

mvn clean install -DskipTests

(The “skipTests” directive is a bit of laziness. There is a test included in the plugin that will fail because of the change that we just made. You can either run this command as it is, or you can edit the test in the plugin to also look for a string of “quite true.”)

Now, when we access the API again, we’ll see the change reflected - without our having to manually upgrade or uninstall/install the policy plugin:

"method" : "GET",
"resource" : "/apiman-echo",
"uri" : "/apiman-echo",
"headers" : {
  "Accept" : "*/*",
  "Cache-Control" : "no-cache",
  "User-Agent" : "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.86 Safari/537.36",
  "Connection" : "keep-alive",
  "Test-Policy" : "quite true",
  "Postman-Token" : "bb900e07-249c-66e4-980a-2c9a70002c45",
  "Host" : "localhost:8080",
  "Accept-Language" : "en-US,en;q=0.8",
  "Accept-Encoding" : "gzip, deflate, sdch"
"bodyLength" : null,
"bodySha1" : null

In Conclusion

From its first releases, apiman has provided users with flexibility, including support for adding custom policies through plugins. In the latest release, apiman has expanded on that flexibility by enabling users to uninstall policy plugins, upgrade policy plugins, and automatically reload policy plugins.


Cross-posted here: