API ManagementArchitecture Best PracticeThe Intelligent Enterprise

API Management Implementation – Lessons Learned

Part 1 of a 3 part series

About the author: Simon Hoare, is an IT professional and customer of ours at a large insurance company. His career spans over 26 years and throughout it has held a number of senior positions, primarily in architecture. In his most recent role, he’s demonstrated proven success in launching, building, and growing a successful API best practice program – moving the organization from a SOA strategy to one in which they’re leveraging micro-services and API management best practices, working with everyone from API analysts to the business. He’s been able to demonstrate not only an impact on the bottom line but also directly tying together business innovation and ideas with existing IT capabilities. Because of that experience we’ve asked him to share some lessons learned along the way, in addition to what he’s found that works well, and what opportunities he’s seen become unlocked through this strategy.

The adoption of an API Management platform within a large organization is a complex multi-year exercise in which the decisions made at the beginning of the process are revealed subsequently to be key drivers of success or failure.  About four years into our API Management implementation I can share a few things which in retrospect could have been done better:

1. Control variation

One of the advantages of having a design time component in the platform is that it becomes possible to establish patterns and generate consistent artifacts which embody architectural standards. OpenAPI and WSDL specifications are obvious examples, but this can be extended to include client and server code stubs, API gateway proxies and proxy policy configurations. The tools for creating consistency should be emphasized and socialized early in the process.

2. Have a platform perspective

The core API management components – design solution, run time gateway, developer portal, lifecycle management and governance – should be thought of as one platform conforming to an overall platform vision. Creating organizational boundaries between these elements – often aligned with the vendors’ product scope – works against a unified vision.

platform perspective of API management components
Have an overall platform perspective of the core API management components

3. Define a resource model

In the REST paradigm the organizing principle is the resource, which is encoded in the REST API’s basepath in the design platform, and which has to be unique for the API to be hosted on that basepath in the API gateway. In the absence of a resource model the API designers are inevitably going to create APIs for same resource, which the team owning the API Gateway will likely modify or even combine. The net result is the running proxy in the gateway cannot be mapped to a single API definition in the design platform, breaking traceability and limiting opportunities for automation.

4. Control proliferation

Our developers have been laboring over their keyboards for several years now, and the net result is a lot of built APIs. This is driven in part by the need to support a mobile channel which for performance reasons cannot accept API payloads with unnecessary data elements, and which also cannot tolerate having to make more than one API call per use case.  This focus is in tension with the traditional SOA view of creating reusable and generalized services which is not resolved in our environment as we’ve focused on unlocking core systems with APIs compared to building business capability building blocks.

5. Use the canonical model

It is very easy to allow APIs to be built in the design platform without leveraging canonical definitions. Bypassing the canonical creates idiosyncratic API models which are hard to maintain, are less semantically clear, are less reusable, and are potentially error prone.

6. Automate the creation of proxies

We demonstrated how virtual endpoints could be generated from the design platform – however we ultimately could not implement this because our basepaths were not unique, which prevented the API from being consistently published.

7. Self-enforcement of governance does not guarantee results

Our approach to governance has been one of self-enforcement, without using any governance or lifecycle management tool. The results have been, unsurprisingly, inconsistent.

Read on for the next part of the series where Simon discusses what the enterprise got right for a deep dive into best practices you can replicate.
Tags

Simon Hoare

Simon is an IT professional and customer of ignite at a large insurance company. His career spans over 26 years and throughout it has held a number of senior positions, primarily in architecture. In his most recent role, he’s demonstrated proven success in launching, building, and growing a successful API best practice program – moving the organization from a SOA strategy to one in which they’re leveraging micro-services and API management best practices, working with everyone from API analysts to the business. He’s been able to demonstrate not only an impact on the bottom line but also directly tying together business innovation and ideas with existing IT capabilities.

Related Articles

Close