Corelation's KeyBridge interface is powerful and expansive.
Core interface technology generally comes one of two ways for third-party integrators. The first way is a complete interface that encompasses the entirety of functions and data available within the core system. The second way is a partial interface, designed for a specific purpose, such as online banking. The problem with the partial interfaces is that they never have the functions needed to produce innovative applications, they only contain functions the system creators assumed a third-party required. KeyBridge is a complete interface, which allows third-party vendors to innovate in ways previously unforeseen.
KeyBridge
KeyBridge is a XML based web service developed by Corelation for accessing their KeyStone core system application. It is designed to allow privilege-based access for third-party integrators, such as digital banking vendors like us. One powerful feature is the ability to wrap multiple functions (called steps) into one network request. This allows us to really hone in on performance, especially when working with a high volume of requests.
KeyBridge description (pdf link)
Corelation has developed the KeyBridge Application Programming Interface (API) that allows vendors full access to the KeyStone application, restricted only by the credit union’s privilege control. The interface is the same as that which is used by the User Interface to communicate with the Core Application – literally anything and everything a user can do at their terminal can be done by a vendor remotely. The design of this product may seem intuitive, but its simplicity provides a powerful tool for a credit union navigating the wide array of vendor choices available.
According to Corelation's President, Theresa Benavidez (pdf link)
Our API, KeyBridge, uses an industry standard XML interface readily available to any third party on the market. Not only does this open the credit union's vendor options, but it simplifies the integration of software, reducing the headaches a company may face when choosing to write to a new core system.
Getting started
We use the .net core and .net standard technology stack for our backend services. Since KeyBridge is XML based, there are no problems using .net core with KeyBridge. Generating the object model from the XSD schema document is done using the xsd.exe tool. Once you have generated the .cs file from the XSD using the xsd.exe tool, you can add the code file to your project to start generating the objects to communicate with KeyBridge.
Once you have the object model, you need an XmlSerializer to convert the object model from c# objects to XML and an HttpClient to send the XML to the KeyBridge web service and read the responses. That's the basics of communicating with KeyBridge.
The steps invloved in sending a request:
- Create request object
- Serialize to XML
- Send XML request to KeyBridge
- Deserialize response to object model
- Process response object
HttpClient and XmlSerialzer
HttpClient does contain a few unexpected behaviors that you should be aware of. It impelemnts the IDisposable interface, which if you're being a good .net citizen, you'd expect to wrap in a using statement like the one below.
You will run into trouble if you use HttpClient like this. You're supposed to reuse the HttpClient throughout the lifetime of the application. Here is a detailed explanation of the problem and how to solve it. The short version is, use a static HttpClient in your application and let the garbage collector dispose of it when your application exits or is restarted.
The good news is .net core 2.1, which is unreleased as of this writing, addresses multiple problems with HttpClient with the introduction of a new HttpClientFactory. Read a more detailed breakdown here on Steve Gordon's blog: part 1, part 2.
The XmlSerializer is subjected to runtime caching, so there is a performance penalty on the first object creation of the serializer's object model. Serializing objects to XML in .net involves serialization assemblies that are compiled during runtime by the JIT compiler. Luckily, the object model is not too large and the assembly is created quickly on first access and retrieved from the cache on subsequent requests. In any case, you should create a static XmlSerializer to handle the serialization.
Object model
The object model generated by the xsd.exe tool creates object lists as arrays. This can be a bit tough to work with, especially for complex requests. You can control the output of the xsd.exe tool to output List<T> instead of arrays []. A small improvement, but you're still adding objects to lists and adding those lists to other lists, and so on.
Extensions to the rescue
For the amount of detailed code we need to create and maintain to handle the Keybridge requests, we needed a better solution. We've created a set of extension methods that handle creating the KeyBridge request messages. We use fluent interface methods that are similar to LINQ extension methods. The important bit is to keep returning the passed in object (c# keyword this) so we can continue the chain. This allows us to chain object creation and option setting functions so we can create request objects with minimal code. It allows us to focus on request creation and forgo a lot of boiler-plate code.
I can't show too many details because of an NDA, but here is a somewhat complicated query that gets a list of tables and functions which is distilled down using extension methods. Normally, you'd see more than a few arrays and new keywords to create this request.
The extension methods fall into two categories: creation and extraction. They are used to create requests and extract objects from responses. Again, we want to reduce the boiler-plate code so we can focus on the intent of the request. Doing so reduces maintenance complexity and improves our ability to create new features expeditiously. You still need to understand the KeyBridge interface thoroughly, however. There is no shortcut to that.
Creation method signature example. We use type name matching to label the object type in the request.
Extraction method signature example.
Conclusion
Using .net core to interface with Corelation's KeyBridge web service works quite well. The ability to batch requests allows us to create high-performance applications and fine-tune performance bottlenecks. KeyBridge is a powerful tool with great flexibility. With flexibility, however, comes its counterpart: complexity. Banking interfaces are inherently complex, so we try to create tools that allow us to use those interfaces effectively and predictably. It is important not only in the code creation process, but in the code maintenance process as well. These systems are continuously evolving and it is critical to be able to reliably update code to match business needs in a timely manner.
