API Advice

API Experts - APIs That Build APIs

Nolan Sullivan

September 15, 2022

TL;DR

Spend time thinking about your API taxonomy. Talk to users to make sure the language you use matches with how they understand your product.
Sometimes you need to build endpoints that deviate from the long-term vision of your API to deliver value to clients. That’s okay, just always have a plan to bring things back into alignment down the road.
Even if you’re building an API product, some tasks are more easily solved with a UI, be strategic about what you ask user’s to do via API and know where a UI is important.
For a good DevEx, relentlessly focus on minimizing your time to ‘wow’.
If you’re PM’ing an API product, you need to build with your API to uncover the points of friction.

Introduction

Akshat Agrawal, is an MBA candidate at Harvard Business School. Prior to pursuing an MBA, Akshat worked as a senior product manager at Skyflow (opens in a new tab). Skyflow is a data vault accessible via an API interface. Akshat was an early product hire at the company and was tasked with building and refining the MVP of Skyflow’s API interface. Prior to joining Skyflow, Akshat worked as a PM for Google Stadia, Google’s next generation cloud gaming platform.

Can you let people know what Skyflow does?

Of Course. So, Skyflow is a Data Vault delivered as an API. There’s a lot packed in that sentence, so let me break it down a little bit. First of all, what is a Data Vault? This is an emerging category of data infrastructure. Instead of sticking your sensitive and non-sensitive data into the same database, which is traditionally how companies have been operating, the emerging paradigm is to create a separate construct called a Data Vault, specifically designed for you to store and compute sensitive data. Sensitive data includes things like PII and KYC (know your customer data), basically anything you wouldn’t want breached.

Skyflow provides data vaults that have all the bells and whistles you’d want: encryption, key rotation, data governance, data redaction, field masking, all of that is baked in. It is a totally managed service that we deploy within our cloud for most of our customers. Then the way that developers interact with the data stored in the vault is through an API. So at Skyflow the API is a big part of the product, in some sense it is the product. The API is used for the entire lifecycle of interaction with your data vault, from creating the data vault, to specifying the schema to actually reading, writing, deleting data from the vault, as well as computing on that data, sharing that data, configuring governance rules. It’s all meant to be done via API.

What does API development look like at Skyflow? Who is responsible for releasing APIs publicly?

Yeah, that’s a good question. Well as you might expect, as a startup the API development process isn’t perfect. When I was at Skyflow, we were definitely still figuring it out. But in general, there are a couple of key steps. First is designing the taxonomy (structure) of the API. This is a bit of a nuance to Skyflow’s business, but because we are a data platform, we actually don’t have a fixed schema. It’s up to the customer to define what their schema looks like. You know, how they want to arrange their tables and columns. And that makes it very different from your typical REST-based API. We had to design an API that was generic enough to be able to serve whatever data schema our customers designed. And so this really exacerbates the taxonomy problem. We had to make sure that we were really thoughtful with the terms we used to describe our resources. We had to make sure that the structure of the API made intuitive sense and that whenever we add a new endpoint it’s a natural extension of the existing taxonomy.

So step 1 was getting the right structure for the endpoints and parameters. Then step 2 would be the actual development, including testing and telemetry for the API. Then step 3 would be rollout. Depending on the nature of the API, we might offer it as a beta; and test with certain customers. We’d assess whether there were any back-compat issues that needed to be accounted for. Then last step, we would prepare the documentation. That is super important. We were rigurious with making sure that the documentation is up to date. There’s nothing worse than stale documentation. And that, roughly, is the full scope of the API development process.

How does Skyflow ensure that publicly released APIs are consistent?

It starts with establishing a literal rulebook for API development, and getting the whole team to buy into using it. We created guidelines which contained rules about how APIs are named, how parameters are named, standard semantics, expected functionality, all that kind of stuff. Ironing out those rules enables developers building new endpoints to get it mostly right on the first go. That’s really important for development velocity.

Building the rulebook isn’t a one-time activity, our API best practices document was ever-evolving. As time has gone on, we’ve gotten to something pretty prescriptive. So now, if you want to add a new endpoint, you should be able to get it pretty close to perfect just by adhering to the things in the document. And that rulebook is actively maintained by our API excellence committee.

If I were to ask a developer building public APIs at Skyflow what their biggest challenge was, what do you think they would say?

Well like I said. I think how you describe your API resources is important. And one specific challenge for Skyflow was maintaining intelligibility across clients and user personas. As an example, some users might call it consistency, while other user’s called it quorum, and still other people might call it something else. It can be really challenging for them to understand the product when it’s presented in unfamiliar terms. That challenge is not technical. It’s more organizational and logistical, and it’s especially hard when you’re in startup mode. You’ve got tight deadlines and customers asking for endpoints that need to be shipped quickly. So really balancing the cleanliness and excellence of the API against time constraints and organizational constraints is really hard. And it’s all compounded by the fact that your APIs can’t really change easily once you launch them.

What about the challenges facing the developers who consume Skyflow’s APIs?

We are a security and privacy product and there’s some problems that can create for the developer experience. As an example, a lot of APIs can afford giving users a static key, but for Skyflow that’s not the case. We have to take extra steps to make sure interactions with the API are safe.

We use a jwt token, which you have to dynamically generate and that jwt token contains all the scopes and permissions that define what data you can interact with.The whole process of generating that token, and getting authenticated to the API is non trivial. You have to get a credentials file with a private key, then run a script on it to generate a token, then you include that token in your API requests. Asking users to perform all those steps creates friction. We saw we had a lot of drop off along the usage path, especially for developers who were just trying the API for the first time.

To address that issue, we built a trial environment into our dev portal. We auto-generate a personal access token that users can use to experiment with the API. But in production, we want to stick with that really robust, secure mechanism.

API architecture Decisions

Skyflow’s public APIs are RESTful, Can you talk about why you decided to offer Restful APIs over say, GraphQL?

I think for our use case, specifically, GraphQL is actually a good option, we are trying to appeal to developers at other tech companies. But ultimately it’s still a bit ahead of the market. I think GraphQL is really cool, but you know, compared to REST, it’s not as easy to understand or as commonly known by developers. So REST still felt like a natural starting point. GraphQL could always be added in the future.

If someone was designing their API architecture today, what advice would you give them?

Yeah, totally. I think API security is something everyone should spend more time on. APIs are the attack vector for a lot of the data breaches which are happening today. It’s really hard to secure the entire surface of your API because unlike traditional services, which are running in a confined environment, APIs try to be universally accessible. I wish I had some more concrete advice, but if you’re a startup, spend time discussing it as a team.

PM’ing APIs

What’s it like being a product manager working on an API product?

I do think, relative to other PM roles, you need to be more technical. That being said, it shouldn’t be a barrier for most people. If you’re at the point where you can make an API request, then you can probably develop and grow into the role. So I definitely would tell people to not let the fear of not being an engineer discourage you.

Like any good PM, you should be a consumer of your own product. And for an API product, that means you need to use your API. That’s the real way that you figure out where the friction points are. And when I say use, I mean really build with your product. Of course, you can get out Postman, get an API token and make an API call. But when you actually go to build something, you start to discover all these little thorns. I built with our API from day one.I had little side projects. In the case of Skyflow, that helped me identify that the definition of the schema was a pain. It was quite difficult to do via API. So we actually built a web UI that could do the schema definition. So, yeah, the TLDR is you have to build stuff with your API.

And of course not specific to an API per say, but at the end of the day, making your early customers and partners successful is the most important thing, so let that guide you. Oftentimes, we would have to make hard trade-offs, keeping the shape of the API completely standard vs. giving a client specific functionality they needed. If you’re PM’ing an API, your challenge will lie in eventually bringing everything back into a state of alignment. You’re managing an ever expanding body of endpoints and functionality and so you really need to be thinking about the long-term. How will we hurtle the cattle and bring the endpoints back into a clean shape as a cohesive product?

What were the KPIs that you tracked against for your product area?

I focused a lot on developer experience. The most important metric that I tracked was our user’s average time to ‘wow’. For a lot of API products, ‘wow’ will be the first successful API request. The time from when you click ‘get started’ to when you make that first successful API request, we put a lot of effort into trimming that time down. And it can’t just be the sum of every step of the process: getting your credentials to the account, setting up your data vault, authenticating a token, creating a well formed API request, sending it debugging. You also need to account for the time where your user is stuck or inactive. They don’t see anything in the documentation, so they give up and come back to it in a day. Because the documentation is part of your product. Reaching out to support and waiting for support to get back to me, that counts against time to wow.

Through a combination of working on authentication, onboarding, documentation, API design, we were actually able to get that down to minutes. For developers, short time to ‘wow’ inspires confidence. And it has a sort of dopamine effect. We feel good when we get that 200 after sending the API request. I don’t know about you, but anytime I start to use a new API. I have this sense of foreboding. I’m just waiting to run into an error or stale docs or something like that. And when it just works the first time, it’s an amazing feeling.

DevEx for APIs

What do you think constitutes a good developer experience?

There’s a lot of things that go into creating a good developer experience, but I would say that at the end of the day it boils down to productivity. A good developer experience is when developers can be productive. This is not just for APIs, this is for all dev tools. It’s all about productivity. A lot of studies show with the proliferation of SaaS tools, Cloud Tools, microservices, new architectures, developer productivity has kind of hit rock bottom. There’s just so much to account for. The amount of hours that developers spend doing random stuff besides just writing and testing good code is way off the mark. The proliferation of APIs should have big benefits in the long term, but currently developers are losing a lot of time understanding partner APIs, looking for documentation, debugging, dealing with authentication.

So when it comes to APIs, a good developer experience is one that makes developers maximally productive when developing atop your API. Unlike most products, with an API you want your users spending as little time as possible with your API. It’s not their job to spend a lot of time on your API. They’re just using your API to get something done. So you really want them kind of in and out the door, so to speak.

Closing

A closing question we like to ask everyone: any new technologies or tools that you’re particularly excited by? Doesn’t have to be API related.

That’s a good question. And I think a big part of being at grad school is my desire to explore that fully. I’ve been really deeply in the world of security, privacy, data and fraud for the last few years. I’m excited to see what else is out there. One thing that’s really interesting to me right now is climate tech. I think there’s just so much scope for software to make an impact in mitigating climate change and so I’m really excited to explore that space more.