In Part 1 of this series, we discussed the lessons learned from a large insurance company during their implementation of an API Management Program. In Part 2, we discussed what they got right and what worked well. In this post Simon discusses the opportunities that a successful API Management Strategy, as well as a Holistic Abstracted Catalog, unlocks for large enterprises.
REST APIs should be scoped to a specific resource – meaning they should return only that resource. This can be inefficient when the consumer wants several related resources or if they don’t want the entire resource. GraphQL is in effect an ‘information service’ providing an endpoint which takes a consumer defined query, and which returns matching data. Adoption of this model removes the need to create what are effectively hand crafted query implementations for the large number of APIs which are just returning data from a single data source.
2. Utilize the capability model
Currently there is no consumer of the information presented through the capability model and its mapped APIs. There is an opportunity, however, to tie that information into an API blueprinting process to identify opportunities for API reuse and API product definition.
3. Include the project perspective
The design platform should be the system of record for API metadata. In our case, however, projects began creating Confluence pages capturing project data, much of which should have been in the design platform:
Defects and defect resolutions for a given API by consumer
Promised delivery dates by activity (analysis, test, development)
Assigned analysts, testers and developers
Signoff by consumer channel
Which environment has a deployed API version
4. Embrace APIs as products
Currently our APIs are entirely tactical, with the APIs invisible to the business except as one of many technology dependencies. If the business can begin to conceive of APIs as real business products instead of IT implementation artifacts then the business could begin to transform into something closer to the ‘everything as a service’ model in which the business leverages external capabilities and also sells its competencies to other organizations via APIs. In this model productized APIs have defined release schedules, roadmaps, support staff, SLAs and business ownership, all of which can be tracked as API metadata in the API platform.
5. Leverage analytics
The API platform can provide insight into business activity driven by APIs through analysis of API calls. These analytic results should be of interest to the business especially if they adopt API as a product vision.
6. Enable agility
Business agility is one the core drivers of SOA, and is a benefit derived from adhering to SOA design principles to create decoupled and reusable services. However creating well defined reusable services is insufficient – in large organizations those services and APIs also need to be discoverable and presented with sufficient information to make them appear as useful component of proposed business solutions. The API design platform’s catalog should be leveraged to expose available APIs broadly.
7. Enable innovation
The design platform exposes a catalog of existing APIs, and can also contain an API blueprint. Having access to current and proposed should enable the business to consider new products with a clearer understanding of potential costs and time to market.
API Management Implementation – What Works
Reading Time: 2minutes
In Part 1 of this series, we discussed the lessons learned from a large insurance company during their implementation of an API Management Program. In this post Simon discusses what they found to work well during that journey.
Decisions and steps we have taken that have proven to be effective in implementation of an API Management program:
1. Define security models upfront
Security policies should not be invented on the fly by each API designer. In our case we identified a limited set of security policies which we wanted to support, and the API designer selected from that list. This has resulted in aconsistentand reliable security implementation.
2. Automate publication to the Dev Portal
The design platform, as the system of record for API data, is the logical point from which information can be published to the Developer Portal. We elected to do this once the API reached a specific lifecycle state. This allowed us to automate the creation of entries in the Developer Portal with API descriptions expressed in Markdown, and with request and response examples presented in the portal along with the OpenAPI specification. By mapping the API in the design platform to various taxonomies we were able to control the layout out of the API in the portal.
3. Adopt standards for completeness
Our initial experience with the design platform led us to realize that the API designer was unlikely to fully define the API, especially to the degree necessary to support automation of policies and API portal integration. We successfully introduced a self-enforcedgovernancechecklist which let the API designer validate their work, and which resulted in higher quality products.
4. Business traceability
Once several hundred APIs have been created it becomes difficult to understand what has been created. To address that we represented a business capability model within the design platform and mapped each API to a part of capability hierarchy. This gives us the ability to look at a part of the business and see which APIs are supporting that function. We similarly implemented a Journey taxonomy, for the same purpose.
Read on for the final part of the series where Simon discusses the opportunities that a successful API Management Strategy as well as a Holistic Abstracted Catalog unlocks for large enterprises.
API Management Implementation – Lessons Learned
Reading Time: 3minutes
This is the 1st part of a 3 part series on API Management Implementation in a large insurance company.
About the author: Simon Hoare is an IT professional and Delivery Consultant at digitalML. Prior to that he was a customer of ignite at a large insurance company. His career spans over 26 years and throughout it he’s held a number of senior positions, primarily in architecture. In his most recent role before coming to digitalML, he 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 adesign time component in the platform is that it becomes possible to establish patterns and generate consistent artifacts which embody architecturalstandards. 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 andgovernance– should be thought of asone platformconforming to an overall platform vision. Creating organizational boundaries between these elements – often aligned with the vendors’ product scope – works against a unified vision.
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 aresource modelthe 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 isa lotof 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 buildingbusiness capability building blocks.
5. Use the canonical model
It is very easy to allow APIs to be built in the design platform without leveragingcanonicaldefinitions. 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 anygovernanceor lifecycle management tool. The results have been, unsurprisingly, inconsistent.