Try Stoplight for free by getting started below, or learn about what kind of API design toolset you need by reading on below.
If you search for “toolbox with tools” on Amazon, the first page of results includes toolkits ranging in price from $20 to $250, including 35 to 450 pieces. There are sets with pink and turquoise handles, in case you need to match your decor; sets that come in rolling trolleys; even a Thor’s hammer–themed toolset!
Though many of these kits claim to be “universal,” the reality is that if you don’t know your needs, this is a bad way to buy tools. It’s tough to know the quality you’re getting when you buy everything in a bundle. If you can’t hold the individual tools, you won’t know how comfortable they will be to use. A toolbox is your collection of tools to solve a problem set. Most people own a literal, general-purpose toolbox. Some people own several toolboxes specialized for solving specific tasks.
All-in-one, prefab universal toolkits aren’t a great solution for APIs, either. Far from being the perfect solution for everyone, full-lifecycle API management products often fail to live up to their “universal” promise. Instead, we recommend shopping for API tools the same way we recommend outfitting your workbench at home—piece by piece, listening to subject matter experts based on your specific needs. Let’s take a walk through the API hardware store together.
Spend Time, Save Money – Look for Purpose-Built Tools
When you set out to build your API toolkit, plan to invest some time in research. You are potentially spending a significant amount of money, and you’re committing to tools and processes that will become deeply embedded in your API teams’ workflow. The tools you buy should be high-quality, purpose-built tools that your developers will be happy to use for some time. They should also be the tools your organization actually needs!
Full-lifecycle tools attempt to cover API design, mocking, development and testing, documentation, integration catalogs, performance and usage monitoring, security configuration and logging, and analytics. That’s a tremendous breadth of functionality in one tooling package. And just as it’s not clear that the company behind the Thor’s hammer toolbox knows what its core competencies are, it’s hard to be confident that a single API-tooling product provides the best tool for all of those categories.
Even if you could be certain that each individual tool in a full-lifecycle toolkit was top quality, that doesn’t mean each will be the tool that you need. Two tools from the same category will have different features and functionality. Given the expense of adopting a new tool, both in dollars and in the commitment of time and resources, you want to be sure that it serves your purposes well. A full-lifecycle provider isn’t likely to allow the same level of customization or provide the targeted features that a standalone product can support.
Spending money on a bundle of sub-par tools isn’t a good long-term investment. It’s a far better plan to carefully choose a few tools that will do exactly what you need now and grow with your API program. Taking the time to do your research now will pay off in time and cost savings down the road.
Know Your Needs Before You Buy
If you live in an apartment, you don’t need a lawnmower. If you don’t own a car, you probably don’t need many socket wrenches. If you have a bicycle, you’ll probably want a set of Allen wrenches that includes metric sizes and an ergonomic grip. You might even want a torque wrench to allow you greater control of how tight your fittings are.
Before you begin shopping for API tooling, take the time to determine where you have the greatest needs. If you are not dealing with a lot of highly sensitive data, you may not need the same level of sophistication in your security tooling as a financial-sector API. If you are coordinating authentication across several microservices, you will probably need more robust testing tools than you would for a stand-alone API product. APIs that serve large numbers of external consumers may benefit from a larger suite of analytics tools than those with a smaller audience.
Know what you need before you begin shopping. Most of us don’t walk into a hardware store without a shopping list and a sense of which tools we already have at home—it’s a recipe for coming home with incompatible tools, duplicate supplies, and a blown budget. The same applies to shopping for API tools. Know what you’re building, what your unique challenges and needs are, and where you will most benefit from investment.
Assess Your Skills Realistically
I’m a pretty handy person. I can replace a disposal, patch drywall, and tile a countertop. I draw the line at electrical repair. If I make an error in one of those other projects, I can fix it—but I don’t trust my understanding of electrical systems enough to get over my fear of setting my house on fire. And I think that’s OK! I know a good electrician, and I know when to call them.
When you make the choice to opt-out of a full-lifecycle API tool, you need to do it with clear eyes. What aspects of your API management are you really prepared to take on? What internal resources do you have for UX design, security, and the like? We would never advocate cutting corners on essential aspects of your API programs nor encourage you to take on more than you can manage. The point is to know where you really need support and where you can handle your needs with resources you already have on hand.
Consider performance monitoring—many companies will already have some internal expertise here. Your API programs may be able to build on established tools and processes from other parts of your organization. If so, you’ll find a double advantage here: you’ll save money by relying on tools you already have, and you’ll have deeper internal knowledge of the tools and data than you would if you introduced a new dependency.
Other needs may be outside your comfort zone. Many SaaS companies are moving away from highly customized, support-intensive individual deployments and toward lightweight, self-serve API interfaces. That shift will require more emphasis on automated testing and documentation to ensure consistency for API consumers. Developers may benefit from mocking tools to simulate common usage patterns in advance since customer support for API consumers can’t be as individualized as for custom enterprise applications. If this sounds like your organization, consider whether you are really prepared to build UX and QA expertise and tools in-house. This may be your “electrical” moment—the point where you decide to call in an expert.
Seek Experts Who Listen
It’s not hard to find companies marketing themselves as the authoritative source on how to manage your APIs. But authoritative answers aren’t necessarily practical, and self-appointed authorities aren’t always flexible. They may be the authority on a particular aspect of API tooling, but you are the expert on your API products. The best partners are knowledgeable listeners.
At my local big-box hardware store, there’s one employee I’m always happy to see. He’s deeply knowledgeable, but that’s not what sets him apart. Because he actually listens to me, he offers creative, thoughtful solutions that meet my needs. He trusts what I say about my goals and skills, doesn’t try to sell me things I don’t need, and asks me thoughtful questions. I get what I need, I leave the store feeling respected, and I’m equipped for success on my projects. That’s the kind of expert you want to help you set up your API management tools.
One of the core principles of the Agile Manifesto is “Individuals and interactions over processes and tools.” That’s really what we’re talking about—API tools exist to serve the people involved in your API programs. Any new partnership should be based on serving the existing needs of your developers and customers and delivering a better experience for those people. Prescriptive processes and inflexible principles won’t get you there—improving outcomes for people depends on all partners listening with a bit of humility and patience.
Stoplight sets out to be the kind of company we’re describing. We’re not trying to be the expert in everything, but we offer high-quality tools targeted at your API design and mocking process, as well as open-source tools for documentation and governance. We’ve embraced the OpenAPI standard and open-source principles, making it easy to customize your tools. Stoplight Platform is cost-effective and scalable, and it integrates readily with your other git-based workflows so you can assemble a toolkit tailored to your needs. Thor’s hammer is not included!