Consistent APIs

When building software components and services for reuse across applications it is more important to strive for consistency rather than to comply with a standard. Why do I say that? Because you can always switch your implementation to be standards compliant. If a bulk of your applications use a particular reusable component you can always treat the existing interface as an adapter that in turns invokes a industry standard API behind the scenes. Note however I am not advocating blindly creating wrappers for components for which mature standards already exist (e.g. If you are trying to use a logging API for java you can evaluate SLF4J API and bindings instead of building a new logging implementation).

This is specifically related to horizontal business capabilities that you want to reuse. For instance, say you need the ability to process credit card payments from several applications and there wasn’t an industry standard at the time you needed this functionality. It is important to have a payment API that your apps utilize rather than wait for a standard to magically appear. Day two, if and when a standard appears you can change the existing implementation without any impact to your existing applications. Okay I am oversimplifying – you might need minor code changes and regression testing. But the bottom line is that you will be in a significantly better position rather than having to change code across your codebase.

Have you noticed how some application interfaces are consistently named and exhibit consistent behavior across components and services? This can be a critical success factor for systematic reuse. Reusable components are not isolated islands of functionality. Instead, they are meant to be leveraged in a variety of applications and business processes. Consistent interfaces provide several benefits:

  • They reduce learning curve when a developer tries to understand and evaluate the asset for his/her need.

  • Reduces technical debt – consistent API reduces the need to refactor code and reduces regression testing efforts as well.

  • They increase the likelihood of predictable behavior across applications. This is critical for assets that get reused across business processes with an impact ultimately to end user experience (e.g. what if your customer can update address when opening accounts but won’t be able to do that when updating accounts?).

  • Eases integration and testing efforts. Consistent behavior can simplify testing reusable assets. If an asset behaves consistently whether it is invoked by a web application or a backend process, knowledge about test data and integration behavior is applicable across multiple projects

  • Makes documentation easier to follow: consistent interfaces can facilitate the use of templates for document generation as well where similar files/hyperlinks can be generated.

Last updated