Design and Deliver Better APIs with a Pair of Top Tools
There’s no such thing as an all-in-one solution for your API tooling needs. If there were, you’d know about it. The reality is that every API program has different needs, which means that every API team must find a set of tools suited to the task. Fortunately, a carefully selected toolbox is often more cost-effective than a full-lifecycle solution, as well as more flexible and functional.
Stoplight and Postman are often presented as mutually exclusive API management tools, but recent polling of our customers showed us that many companies are using both tools for a best-of-breed combination. The approach makes sense – both products are relatively lightweight, low-cost tools, and while they have some overlap, they each offer specialized functionality for different phases of the API product lifecycle. Postman is an industry-standard technical tool used widely during development and testing and for basic technical documentation. Stoplight supports some of the same functionality but is built around the principles of API-as-a-Product and provides top-tier design and documentation features to give API consumers the best experience.
We recently spoke to two Stoplight customers who are also using Postman to find out how they’re combining the tools in their API programs. Pete Walton is the lead sales engineer at Sardine, a fraud and compliance engine that provides unified APIs for financial industry clients who previously had to gather information from various sources. We also spoke with Akshay Bhalotia, a developer experience consultant most recently at Phyllo, a standardized API for pulling data from creator economy platforms. Although the two companies are quite different, we found some patterns in how they use these tools.
Phase One: Enable Technical Teams with Postman
Stoplight customers who also use Postman generally take the same approach – Postman is an internal tool, while Stoplight lets them meet customer needs more effectively.
Postman is a terrific productivity tool for API development teams – it’s optimized for technical users and gets them what they need efficiently. Sardine’s employees are technically skilled individuals, such as data analysts, developers, and technical sales teams. As a result, they use Postman extensively for internal testing, as well as providing hands-on assistance to new clients during the initial integration phase. According to Walton, they do share Postman Collections directly with specific users, primarily enterprise-level customers who have in-house development teams responsible for constructing custom requests and integrations. For technically-minded users, internal or external, Postman is an efficient and familiar tool.
Phyllo uses Postman with a slightly different approach, though still with the same guiding idea. As Bhalotia said, “Any developer who has worked with APIs has heard of and used Postman.” To him, using Postman as a distribution channel for Phyllo was almost a requirement – many developers, both internal and external, will simply expect to be able to use it to explore and test a new API product.
Phase Two: Prioritize Consumers with Stoplight
Some of your customers won’t be as technically proficient and you need tools that will meet their needs, too. Postman is great for testing APIs, but it doesn’t have specialty support for the initial design process. And what about the ongoing support relationship with your API consumers after the integration phase?
These are the areas where Stoplight excels – design and documentation.
Build Better with Design-First Tools
Both Walton and Bhalotia stressed how customer needs drive their choices of tools and processes. Walton repeatedly mentioned that delivering an intuitive UX for API consumers is crucial to attracting and keeping users. Design-first is practically a mantra for Stoplight, and opting to start your API design process with their tools will help you to achieve your desired outcome. As Bhalotia pointed out, “Stoplight has one of the best OpenAPI-compliant UI-based API schema builders, which makes it really easy to collaborate on and discuss API design.” If you value good product design, it makes sense to use tools that align with those principles.
In addition to using Stoplight Studio, each of these companies found additional ways that Stoplight tools helped them meet their design needs. Phyllo is beginning to implement automated Style Guides as part of their emphasis on UX, helping to deliver a more consistent API product, as well as further improving the developer experience. For Sardine, tight access controls are a requirement in the highly regulated fintech industry. They’ve found Stoplight’s Teams features very useful in ensuring customers have access to only the data and documentation they need.
Give Users Documentation That Works
During our discussion, Pete Walton described the way some customers’ eyes glaze over at the sight of tools that look “too technical.” Even seasoned developers occasionally find API documentation overwhelming and inscrutable. Sardine and Phyllo are both making use of Stoplight to provide “friendlier” and more approachable docs.
Walton and Bhalotia both noted how much they appreciate the ease of including working code samples in Stoplight docs. For Sardine in particular, it’s crucial that Stoplight documentation can be hosted independently of code repositories. They need to maintain tight control over their code and data, but still allow potential users to explore real product functionality in the docs. Stoplight gives them that control along with a smooth, intuitive UI. As we mentioned earlier, there are times when Walton provides customers with direct access to Postman, but “ninety-nine percent of the time, [Sardine’s sales team] is just adding customers to the relevant Stoplight teams” to get them access to the documentation they need.
Build Efficiently with a Composable Business Model
The COVID-19 pandemic forced all kinds of organizations to make rapid adjustments. One discovery, for many business and technology leaders was the value of the composable business model. In brief, that means breaking the core products and functions of a product into independent, configurable pieces that can be deployed and redeployed in new forms as business conditions change. In 2023, with market conditions leading many companies to push for leaner, meaner operations, that goal is as relevant as ever.
If you’re thinking that the composable business doesn’t sound revolutionary, that’s probably because it’s not a new idea for most development teams. What is new is the growing recognition that this model has value beyond technical tools, and it can be the basis for building better products and services in any industry. Treating APIs as complete products, with customer needs feeding directly into API design, enables companies to provide value quickly and more efficiently.
Stoplight and Postman offer complementary features that integrate smoothly. Each is, in itself, an example of a composable business model, which means they offer greater value to users. They’re also a solid foundation for building your own composable API program since they make your processes more nimble and efficient, and allow you greater focus on user needs.
Stoplight and Postman are both tools for your “do more with less” toolkit. To maximize their value, invest time in understanding your API development processes, learn where your API products need special support, and assess your development teams’ knowledge and strengths. Do you understand exactly where your tooling needs are? When you do, you can choose tailored solutions and avoid wasting resources on tools that don’t align with your specific needs.
Generally speaking, tools like Stoplight and Postman, which can easily integrate with other systems, are going to be better choices than bloated all-in-one systems. Walton emphasized that overall price and value were important considerations in choosing Stoplight and Postman, as opposed to a competitor that bundled functionality. As a startup in an industry facing a lot of new and complex challenges, Sardine prioritizes keeping overhead low so that its focus can stay on its core product. Composable businesses need flexible, cross-compatible processes and tools that let them create and innovate without cutting into margins.
The composable business model is also about what you produce through your API programs, and flexible tools help there, too. As your development process gets leaner, you’ll be in a better position to pivot quickly to meet customer needs, which is the hallmark of the business model. Bhalotia spoke to this idea when he told us about the principles he uses to choose the right tools: “The two things that matter the most to me are the user experience for my customers and the productivity of my engineering team, in that order.” Postman supports internal productivity, and Stoplight delivers great UX for your API consumers. Together, they’re an outstanding combination for meeting those goals.
Getting “meaner” is becoming more agile and more prepared to adapt on the fly. You want your API programs to be ready for the fight so that you can continue delivering the best user experience possible even as conditions change. Using modular, streamlined tools allows you to focus your efforts on understanding and adapting to customer needs, with the assurance that your tooling won’t impede innovation in your process and products.
Get to the Product Finish Line Faster
As Bhalotia said, Postman is an essential tool for API developers and consumers. However, not all APIs are successful as API products, which is what the composable business requires. Relying solely on one tool may not be sufficient for you to achieve your desired results. Stoplight fills the critical gaps that can keep a good API from becoming a great product by connecting technical resources to users throughout the product lifecycle.
Building API products that are durable yet agile takes thoughtful design, lean processes, and carefully chosen tools. It requires seeing your API as more than a technical resource, which means thinking about user experience throughout your design and development process.
An API product isn’t finished when all the endpoints are tested or when the first customer creates a successful integration. The finished product includes documentation and support, as well as a process for integrating feedback and data to refine your designs and prepare for the next iteration. Together, Postman and Stoplight are an efficient and flexible set of tools to support you throughout your entire process. So instead of thinking it has to be an “either/or” situation, perhaps you can have the best of both worlds! Get started today with a free Stoplight Workspace.