What it Means to be Design-First When Building APIs: Processes and Tools

Steve Rodda is the CEO of Stoplight, a global API design and documentation platform that helps SaaS companies design, test, mock, & document APIs. Before Stoplight, he held various leadership roles in engineering and product management at large organizations like SolarWinds and Cherwell.

In this interview with Kelly Sarabyn, one of the Co-Founders of the SaaS Ecosystem Alliance, he shares what it means to be an API-first company, what “design-first" means when it comes to APIs, and processes and tooling to use in the design phase of building an API.

This conversation is transcribed from our latest episode of the Between Product and Partnerships Podcast, presented by our group The SaaS Ecosystem Alliance. If you're interested in watching or listening to this conversation, you can access the video here and listen on podcast platforms here.

‍‍

Transcript Intro

Steve: A little bit about my background is that I'm a natural born coder. I've been coding since I was eight years old. For the past 20 to 25 years, I've had various roles  including engineering type roles, product management roles, and leading large engineering organizations. Some other companies I’ve been involved in are SolarWinds, LOGICNow, and Sharewell before I got here at Stoplight.

Stoplight quite simply is trying to change the way that people develop APIs. We believe in taking a design first approach; APIs are so critical and so important these days that you should actually think about them upfront and and put them at the very beginning of your development process.

Kelly: Awesome. For the younger people in the audience, or even people who are just new to tech, they're probably used to hearing about APIs in the last couple of years.

What do you think it means to be an API first company? Are all B2B SaaS companies, API first? Is that different from an API product as a product? What does API first mean?

Steve: It's like Marc Andreessen famously said, ”Software is eating the world.” I like to add to that as well, “If software is eating the world, APIs are the teeth”. Whether you think you're an API company these days or not, you are, you're working with them, and your developers are working with them constantly. An API first company literally came from the concept that we should develop our API first.

What I mean by that is way back in the day, you used to actually build your UI and your backend code and all that type of stuff, intermingle it together, and then release it. That became problematic for all kinds of reasons, mostly maintenance, and development speed. 

Once web development came out somebody said, “Hey! Wait a minute, we should probably build these APIs before we build the UIs and separate these things out.” The software development term for that is "Separation of Concerns". That really kind of kicked off this API craze that’s happening today. It started from just separating your UI and your backend code. Now with mobile devices, Omni-channel type of support, microservices, etc., it's taken on a much larger meaning. 

"Today API first means that it's a higher order function; it's something you should pay attention to before you start developing. You should also start thinking about the end users and how the data is going to be used. I really think that API first is a core precursor to what we call design-first at Stoplight."

Kelly: I'd love to unpack that a little more, because it's something we’re seeing in dialogues on the internet.

Related Content: APIs and Integrations Explained for Non-Technical Roles

People are talking about design-first versus code-first. What do those two terms mean? And how should organizations be thinking about that? Are there advantages to code-first?

Steve: I feel like the sage old developer now. Just the other day, I was a young kid learning all these new technologies, but it's an evolution. Prior to code-first, API-first, or any of those things, there's actually database-first; things kind of come full circle. I'm sure we'll talk about GraphQL later, but there used to be this concept that you should design your database first, and then everything else extended from that.

Each one of these is more of an evolution and iteration in our overall thinking about how software should integrate together. It was database-first, then it was code-first, then API-first. We think design-first is the way that you go about doing that. 

I just talked about API-first a little bit, code-first literally just meant, we should think about developing the code, the object models, the relationship models, etc. before we go out there and think about the UI/UX. Design-first is where I think we're really at these days.

What design-first means is that you start thinking of your API as a product, even if it's not. Somebody's using it, right? Somebody is an end-user of it. Somebody has to have that customer experience for it.

You'd sit down and spend tons of time designing your UI/UX; you should spend an equal amount of time designing the developer experience.

That's really where you're starting to think about these things in terms of consistency of use and usability. For example, is one variable called something in one place, but it's called something different elsewhere? It’s about sitting down and actually putting on your product management hat and thinking about the overall experience that people will have with your APIs. This is the next iteration in the design-first era.

Kelly: Over here in the partnerships world, we're really focused on external APIs being interoperable with other SaaS products.

Can there be conflicts between product teams, who are laser focused on what they want the product to do for their users, and partner developer experience, who will want to see similar data models to others in your product categories, they're familiar and it's faster for them to build more integrations?

Can there be a conflict between the data models in the core product and what you might put in the API for the developer? If there's a conflict between the partner developer experience and the end user of your product's experience, is there a way to think about reconciling those conflicts and making choices?

Steve: First of all, I've built many, many APIs that I thought were going to be used for a specific use case only to be used in dozens of different ones. I actually think it's not an either/or situation. It's not specifically defined as "build it for external" or "build it for internal." It's built with what service you're trying to provide in mind and what data can be consumed. 

If you’re a sandwich company, you're in sandwiches; that's the focus. How do I get those sandwiches to people? How do I scale that business? If you step back and develop your API toward the services you're trying to provide and where that person is using it, it doesn't doesn't particularly matter if it's an external or internal API. You should always start with the most external kind of view on it, because that's going to end up with the best product.

If you think customers will be interfacing with it directly, you're going to build it with ease-of-use in mind. While that might translate to customer experience, if it is an external user, internally, that just translates to efficiency and speed of development.Then you start talking about security.

How many people who build internal APIs forego API security because it’s intended as an internal API? Then somebody uses it for external uses and you're in big trouble. I always say start with the most external use case you can possibly design and develop that. Then your product will be ready for any of the internal use cases there are. Services-first is how I would approach it.

What would you say is best practice in terms of process and tooling during the design phase of the API? Who are the internal and external stakeholders that should be involved and is there tooling that people should be using to ensure it moves in a sensible, reasonable way?

Steve: The enemy of all design is time. It's one of those deals where the longer you let it sit on the shelf, it becomes useless at worst case, or at best case, it becomes misleading. It actually can misguide your customers, your end users, which is not great. Any tooling that you can have, or any best practices you can have that can cut down on your design time and increase your shelf life.

Architecture guidelines can be beneficial. Obviously, I am a big fan of Stoplight, but really, you have to go where the developers are at. If you're working on a Git workflow on an agile sprint basis, anything that gets that design in the front of those developers on a day-to-day basis is a big deal and. It keeps your design fresh, so that at the end of the day, developers will have a better experience with it.

Kelly: In terms of security, more and more companies are using OAuth 2.0 for their external APIs; although for customers, that's not necessarily always the case yet.

Related Content: SaaS Integrations 101: Advice and Best Practices From a Sr. Engineer

Do you have a list of best practices for security or things you're noticing that people in the field aren't implementing as much as they should?

Steve: Straight up in terms of security, don't do it yourself, that's my number one thing. I know, I'm making all kinds of people mad when I say that, but the risk is just too great these days to think that you can outsmart somebody or write some custom code to do your security. Products such as Okta are out there to take authentication off your plate.

Millions of dollars and time and hours go into perfecting authentication products. Your home baked user authentication flow, might be okay today, but next week, there could be a flaw in it, and you've already moved on. I would say, first and foremost, from a security perspective, don't hurt yourself. Third-party sign or walkthrough, like you're mentioning, those types of things are too easy to integrate with today. Larger companies can do security better than you can. I would say leave it to a third-party from a security perspective. 

In terms of other standards and protocols that are emerging regarding APIs, there's Async API, GraphQL, and other event driven architecture that people are building these days. Stoplight itself is based around the open API specification like REST APIs. You might sit here and think, “I'm just a REST person.” That's not entirely true. You wouldn't build a toolbox and just throw a hammer in there, hoping for the best. If you're going out to build a big project, you use the best tool for the job. In most cases, these days, it's going to be multiple tools, like all of those that I mentioned, Async API, GraphQL, Open API, etc. they're all on the rise. 

If you go look at the adoption across all those platforms, there's not one of them, that's actually going down. It isn't an either/or scenario or one is being replaced by the other one. You have to think about those use cases across the board and across all of your services, and use the best tool for the job. It's tough to grasp that you might have all of those in your environment, but that's probably where we're at.

Kelly: I'm actually doing a really large study of SaaS's external APIs and when I looked at the top 100, meaning the 50 largest public and 50 largest private SaaS companies, most of them had a variety. Obviously, some of them have SOAP APIs, those that are a little bit older, but they still exist because people were using them in the enterprise space and continue to use them. 

I definitely saw a lot of GraphQL, almost everyone has REST; However, when I looked at 100 series D companies, that was mostly REST, it wasn't as much GraphQL as I was expecting. Based on the early data of the study, it definitely seems like that's where companies are starting for their external API, and as they grow, trying to offer more flexibility, and give developers more options.

‍Do you have any high-level thoughts on the types of use cases that might be a good choice for GraphQL?

Steve: It doesn't get much more flexible than allowing people to run queries against your database. That flexibility for a database or model or whatever it's hooked up to on the back end is one of those things where if you have a power user case, where you want to be able to mold the data and shape the data and get it back in any form or fashion; that's what GraphQL is really good at and really excels at. 

Some use cases like that might be building an application, and a certain object or set of data is going to be used in multiple places, but it's going to be used in different ways. That front end/back end interaction works really well with GraphQL. In fact, Stoplight uses GraphQL for that exact purpose. If flexibility is key, then GraphQL is good. 

If your life craves order nothing beats REST API. It's also extremely easy to wrap your head around, conceptually, the syntactical nature of RESTful APIs, because they often model your objects on the back end in the way that those users would be consuming them. Conceptually, the flow through a REST API makes it a lot easier to maintain, to grasp, and to integrate with, which is why REST isn't going away anytime soon. Of course, these things could start a fight on Reddit, but that's my take on it.

Kelly: Once you have a large number of people using a certain standard or style, there's momentum there. From the company perspective, it's easier to get developers to work with it, because they’re already familiar with it, versus saying, “Hey, you got to learn this whole new standard.” Especially in our use case, when you're talking about partners. They're not working for you full time. Unless you're a strategic partner, they don't want to invest in learning a whole new style, just for your integration.

Stoplight has this pretty large customer base to see what people are doing.

When you look at the last two to three years, what are trends you're seeing in how companies are designing and documenting their APIs? Do you hear developers voicing frustration around a lot of other company's documentation?

Particularly, that it's not up to date. Do you see that improving in the market?

Steve: I see it improving for sure, but the problem is a time condition more than anything else, right. If you go back to what I was talking to before, you used to just build your back end and your front end, that was one one case. Then we added multiple devices. You're talking about iPads, mobile devices, etc. that need to integrate with it. Then we did microservices, and all of a sudden, your different services have to talk amongst each other via APIs. Then you do an infrastructure code, Kubernetes, and containers.

The amount of APIs that you have has just exploded, and I feel like we're just at the beginning of that explosion. People are just now starting to feel the pain of not thinking about all of these different possible interactions: exposing them, securing them, developing to them, maintaining them, or performing the updates.

The shock wave is just now hitting people in terms of how big of a bear all of those changes have become to manage. The biggest change that I've seen is just like that storming phase that's going on right now where people are rethinking their approach to all of these different vectors and APIs they have in their system. Whether that's partners or products, that's the biggest change; maintaining all of these and integrating with all of these is inefficient and causing problems for organizations. What's the solution to that?

Focusing on your developer experience and your user experience is a tangible thing to attack and to address. Product managers need to get more involved in the development and the maintenance of APIs.

You could do the first couple of iterations by quickly and rapidly developing and designing an API, and releasing the documentation and a mock server to some potential customers, whether that's internal or external customers. Then ask, “Does this work for your needs? Will this fit what you need?” Same thing with maintenance changes, you can mock them up really fast today, release the documentation, get a lot of really good feedback, and do some iterations that. You couldn't before. Putting that planning upfront onto the product managers, and really thinking about the developer experience, will, frankly, help with the rest of the explosion that's coming down the road.

When it comes to the developer experience, do you have thoughts on SDKs?  Is this something developers really get a lot of use out of? Or are they so familiar with REST that depending on the complexity, maybe it's not a huge time saver?

It was interesting to see in this study that while most of the top 100 companies had SDKs and a number of different languages; the series D companies didn't, which was surprising to me. I've seen one tool, where you can input your open API specification, and it will whip out all these SDKs for you. I'm thinking either the series D companies don't know about that tool, or it doesn't work as well as the marketing implies. It must require someone to actually go in and either edit it or build upon it and support it in a way that's not programmatic. Is that going to become more programmatic?

Steve: Everything's cyclical. Five years ago, SDK was like a dirty word. You have OWL or like entity relationship diagrams or sequence diagrams. These things have gone by the wayside, because we've put speed of development and agile feature development ahead of process thoughtfulness. If you have Async API, you open it, RESTful API is in there you have GraphQL, and you're doing this multiple approaches for how you access these data align with some type of SDK and way to make it easier on developers to integrate their platforms or consume your data. And that’s going to be required down the road; they're coming back and in a big way to answer your question.

Are there ways you recommend organizations really invest in developer experience? Are there ways you recommend that organizations collect both qualitative and quantitative feedback? Ways that they can improve that experience over time?

Steve: It comes down to old school product management for me. The difference is we haven't thought about APIs that way, in the past. They've been a byproduct of whatever story or whatever feature you're developing. A developer needs a user's endpoint to satisfy some story that got written. They write this user’s endpoint regardless of the fact that there might already be another user’s end point that you could have used. 

It could be as simple as the case field for a first name. It might be named “fname” versus “first name” spelled out, creating inconsistencies across your organization. Without style guides and thinking about APIs in higher order, that's where your developer experience goes wrong. 95% of all API's are developed that way. The only exceptions are probably companies like Twilio, SendGrid, Stripe, people who started with the idea the API is their product. Those are probably the only exceptions. 

That to me is the key to adding product management in there and making it easy. No product manager these days is going to be able to write Open API specifications by hand. The trick is to use low code/no code tools that allow them to build out an API without that technical knowledge. And then potentially send those mock servers and send that documentation to customers and get that feedback, before you ever hand it off to developers, is the best practice these days.

Find a tool that's accessible, that allows your product managers to get involved in the process and manage it like they would any other feature or UI/UX. That's the key to a good developer experience.

What’s the best way that organizations can ensure they're maintaining and supporting the API design and documentation over time? Is the key having a product manager responsible for maintaining and supporting the API? Are there other processes that should be put in place to make sure things don’t go stale?

Kelly: A lot of organizations do invest in that initial build and they may even have great documentation, they put a lot of work into the initial design of the API, but then it can become neglected over time. The documentation goes out of date, or the API itself may go out of date, and the product evolves in other areas and this is not caught up.

Steve: If it's not baked into your developer workflow, it's gonna get stale within two releases. Your documentation and your specification just go out the window, you might as well not have done them, if you're not going to integrate them into your workflow process. It’s also where things like GraphQL become a little tricky, because it's something so fluid, that you're constantly changing on the back end. And those types of deals in documentation can be very hard to keep up with just how fluid something like GraphQL is. 

Build it into your workflow as is number one. The second thing is build it into your CI/CD pipeline. There's a tool out there called Spectral, it's an open source tool, Stoplight heavily contributes to it. It allows you to build style guides for your open API specification. When your developers are building their APIs out there, it's always keeping it in check with your style guides across the board.

This allows you to create the style guides first as those higher order design steps that I was talking about before, and then really hooks it into your continuous integration, continuous deployment platform and it allows the specification to become front and center when you're trying to develop and release code. Tools like that force you to keep good design and force you to keep good documentation up-to-date. When a tool like that is in front your developers all day long, I guarantee they're gonna pay attention to it.

Have you seen as part of that process, any organizations enabling feedback, especially from third-party developers? A lot of partner developer teams have emails you can reach out to but have you seen better ways where a developer who is working with the API and is having an issue can voice or register the feedback?

Steve: So we use a Productboard. We encourage our users to submit feedback to that, just like they would any other feature. That's part of being a design first company, in my mind. You're gonna take your developer experience feedback as serious as your user experience feedback. Similarly you value feedback from somebody who's using it on a mobile device, or whatever the case might be. You build those into the process to fix just like you would anything else. That's the big thing. I would say there's a million of them that are out there. 

A lot of people use Jira and similar products for keeping track of those tools and requests that come in. The important thing is that you take those issues seriously. It might sound like common sense, but trust me, being in the software industry for 20 year if I got a customer who was angry about the user interface versus somebody who wants me to build the API differently for 18 of those 20 years, I would have ignored the API one. I think that's a big part of what's changing, is that those need to be put front and center and on equal footing. That'll help build overall a better developer experience and a better product.

Related Content: The Pros and Cons of Offering Your SaaS Customers Native Integrations vs Third Party Integrations

Do you have any experience with enabling potential prospects or customers to get buy-in internally? Is there anything you would suggest in terms of how to approach executives and show them that value of developer experience?

Kelly: In an ideal world within executive leadership, everybody's on board with the value of developer experience and investing it. Of course, the reality is, sometimes you might own something in an organization, whether you are a solo developer relations person, or you're just an engineer, or a product manager that has been put in charge of this. You see the value and how important it is, but whoever you're reporting to doesn't.

Steve: If you have a developer relations team, then you're halfway there. So that's a really good start, because you're already saying that the relationship that you have with those developers is important and worth investing in and that's a good start. If you don't have one, I would be pitching for at least some investment and in stepping back and looking at those things. 

As for other executives, I hate to sound trite, but you've got to put it in terms of dollars. I'm a developer CEO, and I swore I would never care about those things when I got here. Guess what the first thing I care about is? You have to look at the return on investment and what are you going to get out of it.

If you invest in the developer experience, if it's an external API or external facing product, you literally just get customer service. Bonus points, your NPS scores go up. Developers can be strong advocates in a company. If there's a product that has a great developer experience, and you're evaluating it to buy and it's compared to another one that doesn't have it, they're going to be picking the one that has the better experience when they go through that evaluation process. 

If you focus on that, you're going to win more deals, you're going to get more customer support, and you're going to get more customer success results. Happier customers equals more dollars down the road. It's as important as your UI/UX. That's the parallel I would draw these days is it's becoming as important as your user experience. Most executives these days understand the importance of having good user experience.

If it's internal, it's still as important. It's actually easier to explain in that sense that it just comes with efficiency. If you have a consistent style guide or common way that you're developing your APIs, then developers know that style guide like the back of their hand and internally can just integrate with things much, much faster. It speeds things up across the board.

If you use a tool, prior to getting product management involved, the cost saving is immense. You're building your design upfront and you take an iteration or two on with internal customers or external customers. That saves valuable developer time.What would have happened is, you go to build a bunch of features, and the developers kind of build what they need for the API out of necessity, then they would go to release it.

Then, the infrastructure people at your company would say, “We can't do this, what are you talking about? This is crazy. Go back to the drawing board.” You go back and they develop it again, release it, and then the security people come in and say,  "What are you doing? There's already 10 of these endpoints, what's going on?” So you go back, you do it again. 

That sounds crazy, but that's exactly how most software is developed these days. If you do that design piece up front you can parallelize those things and and give your design to the infrastructure people and the security folks. It's a smoother transition. You should easily be able to put a cost savings to that for your teams and make the case to invest the developer experience.

Kelly: That's great advice. Well, thank you for joining us today. Where should people go to learn more about you?

Steve: I'm all over the place, but I don't have a standard handle across all the platforms. I would just direct them to a Stoplight. I have all my socials on there.

‍