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.
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.