%20(1).png)
Steve Rodda is the CEO of Ambassador Labs, a suite of products designed to deliver API developer experiences. In this interview 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.
If you're interested in watching or listening to this conversation, you can access the video here or listen on our podcast here.
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.
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."
Related Content: The Pros and Cons of Offering Your SaaS Customers Native Integrations vs Third Party Integrations
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.
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.
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.
Related Content: How to build integrations that handle high volume
When it comes to 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.
The problem is a time more than anything else. 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.
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.
This 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.
If it's not baked into your developer workflow, your API will get stale within two releases. Your documentation and your specification just go out the window, and 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.
--
This interview summary is sourced from an episode of our podcast, Between Product and Partnerships. Check it out to hear from more experts working on APIs, SaaS Platforms, and integrations.
