An API program initiative for a large enterprise IT group started with just a few key people. They worked hard to design and implement a small set of APIs that handled a portion of their new platform. After a year of investment, the team had produced several APIs that offered a number of high-value capabilities to the business.
Yet, after all their hard work and excellent design efforts, no one was using the API. Confused, they worked to better understand why. This post outlines the five phases of API integration that they failed to support and how they fixed it.
1. Discovery of API Capabilities
Summary: Developers, product owners, managers, executives, partners, and customers need a developer portal as a single place to discover APIs.
The first issue we encountered was that their APIs could not be found. No one knew that they existed. Even if they knew about the APIs through word-of-mouth, there wasn’t a clear way to view the documentation as it was behind a login screen.
We built out a portal that could be accessed by those interested in understanding what APIs were available. Because the number of platform APIs continued to grow, they were categorised into segmented areas.
The result was a single location to look for APIs and register new APIs as they were added to the platform. Posters were placed around the organisation and announcements were sent to strategic partners to let them know about the new APIs. Even VPs and the C-Suite became evangelists, sharing the link with people in the organisation!
2. Onboarding Developers
Summary: To ensure developers can quickly get started with using your API, define a clear onboarding process.
The next step was to determine how to onboard developers to help them generate API tokens for their development in a non-production environment. When we first reviewed their processes, there was one person in the entire company of 500+ developers responsible for generating API tokens. Not only is this not scalable, but is introduces significant friction that would cause about any developer to skip the APIs and try to access necessary databases directly!
Two approaches were taken: offer a low-friction form for onboarding partners and external developers, and no-friction method for internal developers. The partner onboarding required a short form to be filled out, detailing the desired integration and the API operation(s) they wished to use. For some partners, this is something they could do themselves. For others less familiar with the APIs, a representative for the partner would handle it (along with stewarding the process with the legal department).
For internal developers, non-production APIs were available immediately for integration. Some API operations that could not be virtualised or were intended for a very specific audience were not included automatically. However, a simple request form would allow for the API token to be upgraded to access the sensitive API operations when necessary.
Prior to this onboarding process, only three teams were using the API. After this process was introduced, several dozen teams had been onboarded and more expressed intent to onboard within the next 3-6 months.
3. Map Their Needs to Your API
Summary: It is necessary to help developers, partners, and customers to map their solution to your platform API capabilities. Be sure to offer tutorials and reference documentation as part of your developer portal to help them get started quickly.
Most of the knowledge of what the API could do was housed within the minds of five solution architects. They could tell you exactly which API operations would be necessary to create a particular kind of app or integration. Yet, their calendar availability was so limited that it was difficult to gain their insights into how the API could solve a particular need.
The next step in the journey was to offer case studies, examples, and extended documentation to help teams determine which API operations would be appropriate for their solution. Documentation was expanded to include a summary of what an API did at a high level, sufficient for a non-technical audience to determine if the platform would support their idea. Case studies were used to explain how APIs enabled faster integration and avoided building the same behaviour all over again. Examples helped developers understand how to quickly write production-ready code to integrate APIs.
The time required to determine if the API platform capabilities existed for a solution went down from months to hours.
4. Exploration of API Capabilities
Summary: Documentation tells only part of the story. Allow hands-on exploration of API capabilities using a try-it-out feature – without the need to code.
Just because your API documentation indicates that something might be possible doesn’t mean it will be. Many stories could be told of abandoned projects that started with an assumption that an API worked a specific way, only to find out that this isn’t the case. Several projects had to be delayed or abandoned late in the game when consumers realised that the platform API capabilities available may be missing a specific feature.
The addition of try-it-out features of API reference documentation, using tools such as Swagger UI or Apimatic, went a long way to determine if an API will operate as expected. It helps teams make this determination early, allowing sufficient time to request new additions to the API and have them scheduled as part of a future release.
5. Go-Live
Summary: As developers code up the solution, ensure the performance of your API isn’t negatively impacted through the use of control and traffic limiting, analytics, and reporting.
While they had implemented an API gateway, they failed to establish proper rate limiting to reduce the negative impact of specific applications using their API platform. This became apparent when their cloud resources were being used near 100%. While they had spending caps established in their cloud configuration to avoid a surprise bill, they needed additional reporting and analytics to determine the problem.
Several dashboards were established to identify the issue and prevent future problems. After performing some analytics on the log history, they realised that a bug in an application was causing a specific API to be called 10x more than the previous release. With help of the reporting and analytics, the team was identified, the problem shared, and the issue was resolved.
In addition, developers were given the opportunity to see their own API usage from the developer portal. This helped solution teams to self-diagnose issues when rate limits were exceeded. For API producing teams, they were able to see how their APIs were being used, identify unused capabilities, and make appropriate adjustments to their roadmap to support their current and future consumers.
Wrap-up
With help, the team expanded their APIs into a complete developer portal that addressed all five phases of the API integration process. The result is an API platform that is being used to create new internal apps, partner integrations, and externalise their platform through a variety of channels.
Review the five phases of API integration and determine where you might be able to improve the developer experience of those using your API platform or product.
