Why Don’t API Platform Efforts Deliver?
Your API platform initiative has failed to deliver the business results you anticipated. Adoption by both customers and internal users has stalled. I’ve been in your shoes.
From my previous experience working on LiveRamp’s API platform initiative, I’ll delve into what worked and what didn’t, then discuss common problems that API platform teams run into and how you can address them.
While I was at LiveRamp, we experienced explosive growth, going from fewer than 100 engineers to over 500 in just two years. This rapid scaling brought internal friction and led to shipping products to customers at a slower pace. To combat this, we decided to build an API platform to streamline how teams launched new APIs.
Our goal was to bundle all the common requirements, such as authentication, documentation, deployment, etc., into a seamless developer experience. The scope of this project ended up being bigger than anyone anticipated, in no small part because of the scarcity of tooling available for building enterprise-grade REST APIs.
This experience led me to found Speakeasy. I was determined to use my learnings from LiveRamp to create the toolchain I needed to build the API platform.
Building an API Platform in 2019
Our North Star goal was to make it possible for a new hire to onboard, design, build and ship a new service within a week. Public or internal, it didn’t matter. To hit that aggressive target, we designed our platform to act as an API incubator: Service designs would come in, and a fully baked API available in production would come out the other end.
The API incubator would take care of:
- OpenAPI specification creation: A custom-built domain-specific language (DSL) styled after Amazon’s Smithy was supposed to remove the burden on the team to understand the OpenAPI format. The API incubator would create the spec for the engineer.
- Governance: To maintain consistency, we developed a strict governance workflow that ensured APIs adhered to RESTful principles, naming conventions, security standards and data privacy regulations. Our platform automated much of the governance process, enforcing these rules at the design phase through our custom DSL and during CI/CD pipelines.
- Server stubs: To ensure a seamless transition from design to implementation, our platform generated server stubs off the DSL. These stubs were skeleton versions of the API with routable endpoints, request handling and mock responses. This allowed developers to start working on the business logic immediately without waiting for the entire API infrastructure to be set up.
- Authentication: A proxy layer was built to communicate with LiveRamp’s API gateway. The authentication component verified the identity of users or services attempting to access the APIs, ensuring that only authorized consumers could interact with the API endpoints.
- Routing: The routing functionality directed incoming API requests to the appropriate backend services based on the request path, parameters or headers. Efficient routing is crucial for managing traffic and ensuring the correct service endpoint handles requests.
- Registration: Registering with the API gateway was essential for integrating the API services into the broader API management ecosystem. This step made the APIs discoverable and manageable through the gateway, facilitating traffic control, monitoring and policy enforcement.
We were building during the peak of the microservices craze and focused heavily on building the infrastructure that would allow us to handle scale.
In hindsight, we may have been better served building tooling focused on ensuring robustness and easy integration — what is now often termed the “developer experience.”
Some things that we should have thought about:
- SDKs: Nothing improves the speed of API integration like SDKs. Libraries in your user’s preferred programming languages can boost time to 200 by as much as 60%. Developers can focus on building features that matter rather than wrestling with the nuances of HTTP requests and response handling. We completely missed this one. We left every team to develop their SDKs, which meant that the quality of the SDKs and their interface were inconsistent. Teams struggled to integrate with our APIs both internally and externally.
- Contract testing: The cornerstone of a seamless API ecosystem is ensuring that both the API and its consumers adhere to the predefined contracts. Implementing rigorous contract testing slashes integration headaches by ensuring that any changes to the API do not unexpectedly disrupt existing consumer applications. It’s akin to a trust pact between your API and its users, promising that it remains a reliable foundation upon which they can confidently build as your API evolves. This was a blind spot in our strategy, leading to integration challenges and a lack of confidence in the stability and predictability of our API behavior over time.
- Observability: Transparency within the API’s operational dynamics is not just beneficial, it’s indispensable. Providing developers with tools for observability — comprising detailed logging, real-time monitoring and precise tracing — transforms debugging from a tedious task into a strategic advantage. It empowers users to pinpoint issues quickly, understand usage patterns and optimize API interactions. Our oversight in fully embracing observability meant developers often navigated in the dark, making it difficult to diagnose issues and optimize their applications’ interactions with our APIs.
- Versioning: Thoughtful API versioning is the linchpin for balancing innovation with stability. A clear, consistent versioning strategy ensures that improvements and expansions don’t come at the cost of existing integrations. It respects the developers’ need for predictability, allowing them to upgrade at their own pace without fear of sudden breakages. Our approach underestimated this aspect, resulting in unnecessary friction for developers as they faced unexpected challenges in maintaining compatibility with our evolving API landscape.
Our approach was very focused on the internal aspects of API development. We were building a platform that would make it easy for our engineers to build and deploy APIs. We didn’t focus on making it easy for users to integrate with our APIs. This was a big miss.
What Went Well
We succeeded in dramatically accelerating the building of new services at LiveRamp. After a team had adopted the API platform, new services took roughly three days to deploy into production. Most of those gains came from automating the creation of the documentation and the registration with the API gateway.
The proxy layer was important in bolstering our API platform’s capabilities far beyond the initial acceleration of service deployment. It served as the first line of defense, implementing robust security measures that included SSL termination, rate limiting and IP whitelisting to ensure that all incoming traffic was authenticated and authorized before reaching our backend services. This layer was instrumental in protecting against common security threats and vulnerabilities.
Our governance layer was also a success. It was a pain to set up, but once it was in place, our linting rules ensured that our APIs were consistent and adhered to best practices.
So our systems worked, and API production was a fairly well-oiled machine once it was going. And yet, we weren’t seeing the business impact we hoped for. Both internally and externally, adoption ended up becoming a bottleneck to the effectiveness of our program.
What Didn’t Go Well
In hindsight, the DSL wasn’t the right technology choice. We had fallen victim to that common temptation of engineers: the exciting, but low-value, technical challenge. Building the DSL was a lot of fun but, ultimately, counterproductive. OpenAPI is not perfect, but it is, by a large margin, the go-to interface for defining a REST interface. Internal adoption of our API platform took longer than anticipated because of internal resistance to learning a new DSL. Every time a new hire was onboarded, this situation repeated itself. They would ask, “Can I just write OpenAPI?”
As foreshadowed, the second (and bigger miss) was the focus on scale at the expense of user experience. You can create the most useful service in the world, but if it’s not easy to integrate with, nobody will use it.
Our public APIs, in particular, struggled with adoption. For our customers, integrating with our API was planned for next quarter, next month, next week — always on the road map, never prioritized. The problem was that it was simply too difficult to integrate. We had underinvested in the tooling that could have made it easy and paid the consequences.
Avoiding Common Platform Challenges
For those navigating the complexities of API platform projects, here are my recommendations:
- Embrace standardization and OpenAPI compatibility: The allure of custom solutions is strong, but the benefits of aligning with standardized, widely adopted tools like OpenAPI cannot be overstated. These frameworks offer a balance of flexibility and structure, facilitating easier adoption and integration across teams. They will also reduce onboarding time for new hires as your team scales.
- Focus on developer experience: If you’re building a public API platform, integration is revenue. If you’re building a service-based architecture, it’s how you realize efficiency gains. Focus on reducing the barriers to integration. Create great SDKs so users can integrate without leaving their IDE. Provide great docs so that if they do leave, they can easily find the info they need.
- Be on the lookout for drift: Whether you’re using a custom DSL or OpenAPI, the effectiveness of all the tooling you build is bottlenecked by how accurately your source of truth mirrors your code. If you’re building a new API, there are a lot of API frameworks (like FastAPI) that can generate an OpenAPI spec for you to prevent drift. If you have an existing API, consider setting up some monitoring to check live traffic against what’s documented in your spec.
- Invest in governance: Cultivate an environment that prioritizes API design and governance. This can go wrong if you create an API governance council, which usually causes API development to halt. Try to give your developers tools to easily check their specs with robust linting rules that check for consistency and correctness.
If implementing these recommendations seems daunting, don’t worry. I’ll be back in a couple of weeks with another article. In the meantime, connect with me on LinkedIn and ask me any questions you have!
