So far our series on getting the most ROI out of your API has looked at how to ensure the creation of your APIs align with an overall business goal and are being implemented with a strategy in mind. With business decisions in place, we've moved on to some more technical issues, such as the reference and API architectures, and the choice of API specification formats. Now let's look at the range of API lifecycle tooling available.
When choosing API lifecycle tools, you may need:
- API design and lifecycle tools that support both test-driven development and a contract-first approach and that work with your chosen
- API specification format
- API testing tools
- API performance and monitoring tools
- An API gateway
- API management providers that help you to securely publish and manage your APIs in production
There are also tools available to document your APIs for developers, developer hub tools to build a community around your API, and analytics platforms to measure the impact of your API strategy. But we'll deal with those in subsequent chapters when we bring the technical and business side back together again. In this chapter we look at choosing the API tech stack that your team will use for creating and managing APIs.
How do I choose which API tools to use?
Choosing tools is an iterative process, according to Daniel Cerecedo, founder of the API consultancy Byteflair. "The languages and frameworks you are using will impact on the kind of tools you have available. For example, there are things in [the OpenAPI Specification] you cannot do, like having the same endpoints give different output schemas based on the given security context. For now, that is not something you can reflect in the specification language. So if you're very comfortable about one kind of stack but have very specific guidelines on how to do something like security, then you may have to make a choice about not using that specification format. You have to weigh all of that up," says Cerecedo.
He adds that there are other examples of interrelated products that may influence your tech stack choices. For example, some API management providers don't support some tools, so again, that may influence your choices. Having documented the reference architecture and chosen the architectural type and specifications language will help you make decisions around what other components to use in your API tool stack.
"You need a clear view of your tech stack and in particular your business requirements, and that will help you make specific decisions around what is constraining your development," says Cerecedo.
"For us, when working with businesses building APIs, it is important to understand the whole context of what they are doing, why they have chosen the technologies they have chosen, and how that fits into their business strategy," says Cerecedo. "From there, we can suggest, maybe you need to change this piece of your stack because you will get more productivity or because you will need some custom documentation."
Cerecedo says a good starting point when helping technical teams to choose their tooling is to start with the language or a framework with which your team is most comfortable. "You have made an investment in team skills and what makes that return on investment is getting things done in the fastest time possible," explains Cerecedo. Some specification formats and general tooling are more mature than others, which means there are more coding libraries and frameworks available for developers in particular programming languages.
Marc MacLeod, founder and CEO at API lifecycle tool Stoplight.io, gets a glimpse of what tools API teams are using by understanding what integrations his customers are requesting. Of the customers that Stoplight works with, "mostly it is a bunch of integration requests for specifications versioned on GitHub, most API teams are looking to build a GitHub sync," says MacLeod. To help technical teams use Stoplight with GitHub, the toolmaker created its own API to assist developers interested in exporting and importing from GitHub into Stoplight. Likewise, Mulesoft has created a plug-in to the Atom.io integrated development environment (IDE) called API Workbench (a Mulesoft is the parent company to ProgrammableWeb). The plug-in is for coding API descriptions using the RESTful API Modeling Language (RAML) API description format. Similar to what Spotlight.io has done with GitHub, API Workbench leverages Atom's capabilities as an IDE that can do things like autocomplete, validation, colorization of code, parentheses/brackets balancing, etc. when coding API definitions. It can also act as a full-blown git client that can import and export API definitions to GitHub.
Stoplight also sees a number of users seeking to monitor APIs, so Runscope often becomes a part of their tech stack as well.
Abhinav Asthana, CEO and co-founder at Postman, says his tool is used by API developers at all stages of API development. "We believe the API development workflow is broken and Postman is the tool to complete the chain," says Asthana. "Postman at its core acts as a companion for developers when testing and documenting their APIs and integrating them with frontend and backend apps."
Abhinav Asthana
Asthana explains that tech teams start using the tool to explore and learn about an API, whether that be an internally built API or a public API that is being assessed for consumption. "There is a lot of manual testing that developers would need to do, and the getting to know the API is what Postman helps to do. Then building on top of that, the basic use case is that Postman has more tools to help developers build a lot of APIs.
"The norm in the new world of software development is that visibility of APIs is not really well done," says Asthana. "So we mapped out the API development cycle: the code for an API, testing, documenting the API...you want to put it together, and publish the API. Our core hypothesis is that the data flow across these different aspects of the API lifecycle is broken. Moving from backend code to frontend or to automation, you need to communicate with your APIs. So Postman acts as the communication chain for all the developers involved in the process."
Asthana says that today, among the thousands of developers he has spoken to, the majority of businesses use a mixture of both internal and public APIs. "APIs have taken away a chunk of work," he says. You might use Stripe so you can get payments done, if you have Amazon S3 you can do storage. Businesses want to build prototypes faster so they adopt external APIs and they use them in combination with the internal APIs they are developing. It might even start with just consuming external APIs, but it quickly becomes a mix of consuming internal and external. Another example we have seen is partner APIs, where APIs are shared between companies for an integration they are working on. These happen a lot in today's developer world."
API lifecycle tools like Postman need to model the best practices described in this decision series. One of these is to see the starting point for an API strategy as being about customers, and defining the customer segments and creating customer journeys comes first in setting up a successful API strategy. By the time you've arrived at building the API from a technical perspective, those customer journeys have become user stories with specific requirements, and you can use that API tooling to check each stage of building the API against whether it is still meeting those user story needs.
Micha Mazaheri
"Postman has millions of users right now," says Asthana. "Our development community is about three million users, with half of those being active users each month. You can bring in any API specification format you like to work with in Postman collections, so you are never locked in, and you can integrate Postman with any of your other tooling."
Jérôme Louvel, CEO of API and software development tooling company Restlet, says that, like Stoplight.io's MacLeod, one of the major tooling integrations developer teams are asking for is GitHub. "What we see frequently is people using GitHub to store their API definitions. Once you have the API design stable, you have to communicate this design. One approach we frequently see is [for them] to publish the documentation. On the more technical side, this is about being able to store the API contract specification in a repo and keep the history. We see that frequently, and GitHub is where dev teams are storing it."
Louvel says that when choosing an API tech stack, picking tools that encourage collaboration and allow teams to iterate quickly is most important. He says as teams take more agile approaches, they need to define their tools so that projects can reuse processes and knowledge built up in previous projects.
Micha Mazaheri, CEO and co-founder of API tool Paw, says the goal of the product is to improve the developer experience without locking people into any platform. Developers can open their API from any specification language in Paw and see endpoints, and visualize requests and responses.
What is the role of an API management provider?
There are a variety of API lifecycle tools available that help development teams consume, test, and build APIs. Once an API is created, it needs to be hosted on a server and made accessible via an API gateway. Among other things, most of the API management providers help with all the thorny governance-related tasks like managing consumption use, setting limits, managing authentication, tracking analytics, and ensuring uptime. API management providers are often commercial providers who also assist companies with developing and implementing their API strategy. For those more comfortable with open source, a range of open source API management solutions is available.
A to Z of API Lifecycle Tools and Management Providers
This is just a small sampling of the tools available to assist with all stages of API design, API management and API Ops. It's by no means intended to be comprehensive. ProgrammableWeb regularly reports on new tools and products available to help support API providers throughout the API lifecycle process.
Apigee is an API management provider now owned by Google that aims to support businesses seeking to succeed at digital transformation by reorienting towards an API approach.
APIMatic and API Transformer provide sophisticated automatic generation tools that can create high-quality software development kits (SDKs) and code snippets from API specification formats (APIMatic) and can convert between various specification formats like the OpenAPI Specification (formerly Swagger), RAML, and API Blueprint (Transformer).
API Science is an API performance monitoring tool for internal APIs as well as helping developers monitor external APIs they may be consuming in their workflows and products.
API Serverless Architecture products help businesses design, build, publish, and host APIs using a cloud-based server infrastructure.
Apiary (recently acquired by Oracle) is an API design and lifecycle tool that is based on contract-first design and encouraging test-driven API development.
APInf.io is an open source API management platform that includes an API catalog, analytics data, and API management features.
API-Platform is an open source PHP framework for building Web APIs.
Apollo creates open source and commercial tools to assist with the creation and consumption of GraphQL APIs.
Auth0 is an identity management solution for authenticating and authorizing APIs.
ClearBlade is an API management provider for the Internet of Things.
Distil Networks API Security provides tools specifically for monitoring and resisting attacks on APIs, such as DDoS, SQL injection, and other techniques aimed at overloading an API.
GitHub is an open source git repository hosting service that allows for the distributed management of source code, version control, pull requests, and commenting. Users can also store their code in private repositories.
Hitch is a service provider focused on helping businesses to grow its developer communities by ensuring up-to-date documentation.
Iron.io is a serverless platform for API-driven workload management.
Mashape offers a range of API tools, including an open source API management solution, an analytics tool, and a developer hub template. It's API catalog was recently folded into RapidAPI.
Mulesoft Anypoint Platform is a full-service suite of tools for not only designing, building and managing APIs and their lifecycles, but also for incorporating them into sophisticated workflows that involve orchestration and transformation. (Disclosure: the MuleSoft Anypoint Platform is offered by Mulesoft, the parent company to ProgrammableWeb).
OAuth.io is an authentication tool for API providers.
Paw is an API lifecycle tool for composing API requests, inspecting server responses, and generating client code out of the box.
Postman is an API toolchain that helps API providers run, test, document, and monitor APIs.
ProgrammableWeb is the go-to API resource with news, tutorials, analysis, and the world's most extensive catalog of public APIs and SDKs.
RedHat 3scale is an API management provider, offering a cloud-hybrid architectural style that connects backend APIs to a gateway for traffic control and security enforcement and plugs that into an API management cloud-based service that manages monetization, analytics, and developer workflow features.
Restlet is a full suite of developer tools, including DHC for API testing, Restlet Studio for API design, and API Spark for serverless API creation.
Runscope is an API testing and monitoring service.
Sapience is an automated API security and testing tool.
Stoplight is an API lifecycle tool suite with a mock server product, a single-source-of-truth API design system, an API documentation provider, and an API automated workflow builder.
Stormpath is an identity and user management solution for API providers.
Tibco Mashery is an API management provider that provides a full suite of services, including API design within its solution, developer portal management, access and security gateway services, and API analytics.
Tyk is an open source API gateway and management provider.
In our next chapter, we review security issues related to APIs.