API Advice
The Speakeasy API Landscape
Sagar Batchu
June 30, 2022
Two weeks ago Postman published their API Platform Landscape (opens in a new tab). They’ve done a great job highlighting some of the organizational challenges faced by companies building APIs. We at Speakeasy wanted to chip in with our own two cents. Specifically, we wanted to highlight the day-to-day challenges facing developers on the ground when they’re building and managing APIs.
Our thoughts have been shaped after spending a lot of time over the past 6 months talking to developers about their experiences building & managing APIs. To put some numbers behind it, my cofounder Simon and I have spent a combined 70 hours interviewing over 100 developers about their experiences. All of that goes into our work at Speakeasy, and in the spirit of openness, we wanted to share our learnings with everyone else. So, without further ado, here’s what we have learned…
Trends
Developers want good UX
We touched on this in an earlier post, but developers are increasingly demanding that the tools they use have a great UX. Tools should largely abstract away complexity without becoming a black box. This doesn’t mean just throwing a GUI in front of the terminal. Developers want tools that are embedded in their existing workflows. This may mean that a tool intended for developers needs to have multiple surface areas. Features may exist as a CLI, VS Code extension, Git Action, Web app, React Embeds, API endpoint, etc. DevEx should prioritize helping the user accomplish their task with minimum friction and deviation from their existing workflows, and be flexible on where/how that feature is exposed to users.
A “Design-first” approach has limits
The “Design-first” approach to APIs is often presented as a virtue, to be contrasted with the dirty sin of a code-first approach (implementing the API without formal design). Most companies will claim they follow a purely design-first approach, however talking to developers on the ground, we found a much more nuanced reality. In fact, it’s almost always a mix of the two. Many teams confessed that they felt writing the whole Open API spec was a tedious exercise for little gain. In their weaker moments they would often forgo the full open API standard in the beginning in order to get started faster, then they would go back and generate it later for the purpose of documentation.
Different API frameworks for different jobs
GraphQL, gRPC, Websockets, are all hot on the block, meanwhile RESTful still constitutes the vast majority of APIs (80+%). Although the twitter debates continue to rage and there will always be champions for different paradigms, we see things eventually settling into a comfortable coexistence. Websockets are great for real time applications, gRPC is great for microservice architectures, GraphQL is a great choice when you control both the client and the data source, and REST is great when you are/will be working with external consumers. We expect that in 5 years time it will be very normal for companies to be using all of the above as part of their technical architecture.
API Platform teams are choosing to build on top of the best
Thanks to a tight labor market and the Cambrian explosion in 3rd party dev tools, platform teams have switched tactics when it comes to how they support application developers. In the past, internal teams struggled with the sisyphean mandate of trying to handroll an entire scaffolding to support their companies development. We’re seeing a new trend emerge, where lean platform orgs have the mandate to pick the best vendor products available, and stitch them together to create something tailored to their own business’s needs. This helps to keep the company’s resources focused on the creation of differentiated value for their customers.
Challenges developers face
API testing is still limited
When it comes to exhaustive testing of an API, there can be a dizzying number of parameter permutations to consider. So, while it’s great that developers have tools that let them easily mock an ad hoc API request, creation of a test suite for production APIs can be a major pain point. Similarly, test suites for internal microservices (understandably) don’t get the same attention as endpoints used by external clients. However, oftentimes the external endpoints rely on a collection of microservices to work. It can be hard to effectively test the external endpoint if there’s no corresponding test suite for the microservices it relies on. If behavior changes is it because something in the external endpoint changed, or one of the underlying microservices?
API usage is hard to grok
Which customers use this API? Can this old version be deprecated? Is anyone still using this parameter? All common questions developers ask, all unnecessarily difficult to answer. The lucky developers have Datadog dashboards and full sets of logs in warehouses. However, many developers lack this sort of reporting infrastructure. It’s a big up front investment to set up, and an expensive ongoing cost (opens in a new tab). Small orgs can’t justify the upfront time investment, and even larger orgs often go without for internal endpoints. The result is that developers lack an API-centric view where they could easily get a real understanding of how their API is being used in the wild. This makes it difficult for new developers to quickly grok how the API endpoints are used by consumers, how they work internally, and what to consider when working to evolve the API.
APIs are stuck on v1
When companies roll out an API, they will confidently put v1 in the API path. This is to highlight that in the future, they will be evolving the API and rolling out a new version, v1.1 or maybe even a v2 someday. Often though, the API never moves past v1. Now, this could be because the developers who built the API were oracles with perfect foresight and the API has never needed to be changed. In that case, hats off. More commonly though, the APIs failure to ever evolve is a byproduct of a broken platform behind the scenes. In conversations we heard devs say over and over, “We know it’s going to be painful down the road, we’re trying not to think about it.” Without a robust platform providing scaffolding, versioning APIs is a near impossible task. Teams opt to live with the pain of never updating their APIs. In cases where the team gets really desperate, they may change the behavior of the v1 API and brace themselves for the storm of angry client emails.
Every problem with APIs is exacerbated for internal APIs
It’s been 20 years since Jeff Bezos’s (in)famous platformization memo (opens in a new tab). At this point, most software companies have formally adopted a microservice architecture mandate; there’s no doubt that companies are chock-a-block with services. The problem is that microservices tend to get micro-resource allocation when it comes to their tooling. All the problems we discussed: grokking usage, exhaustive testing, service evolution, are exacerbated for internal APIs. This leads to stale documentation, unintended breaking changes, and unexpected behavior. Left to fester, it can create a culture where developers become reluctant to trust that a service works as described. They will spend time interfacing with internal teams to make sure that the service works as they expect. Loss of trust in reliability has real costs in terms of developer’s productivity.
Developers lack support from the wider org
APIs are an inherently technical product. They are built by developers, and they are consumed by developers. It’s therefore understandable why organizations have siloed all aspects of managing APIs to their development teams. But if you consider that APIs are a product line for many businesses, that is foolish. APIs require customer support, and product marketing and all the same resources as a conventional software product. When API development teams are left to handle all these aspects of product development on their own, they either: 1) do it poorly because it’s not their expertise, or 2) don’t have time to develop new features, because their time is sucked up by other management concerns.
