Software development now depends on APIs of all kinds. We build our own APIs for various apps, and also need to integrate with external APIs. There are tremendous advantages we get from this connected architecture, but the tradeoff is additional complexity.
Fortunately, there is an expanding set of tools that help during every stage of the API lifecycle. Generally, the API lifecycle includes API design and mock testing, debugging, automated testing, documentation, monitoring, and publication.
Requests and responses are naturally at the heart of working with APIs - but today’s event-driven applications require both making and receiving calls asynchronously. This requires more powerful design and mock testing, debugging, and frequent automated testing to deal with system complexity. In addition, users expect machine-readable descriptions which enable automation in monitoring and can help advance an API to the publication phase of the lifecycle. In order to efficiently take an API through this lifecycle, you can use an assortment of robust tools including HTTPie, cURL, RequestBin, Serveo, ngrok, Stoplight, SwaggerHub, Jenkins, Travis, and our own tool - Postman.
Make and Inspect API Calls
Whether you are building or consuming an API, you’ll need to make requests and review the responses. Eventually, these API calls will come from code, but often you’ll want to see them in the raw first. Even with the best possible documentation, inspecting live results helps you check for accuracy, responsiveness, and understand what’s possible.
The classic command line tool, cURL is how many start their experience with APIs. cURL was built for all kinds of data transfer protocols and formats, but its defaults work well with a typical HTTP API. There are dozens of flag combinations to set headers, request methods, and content-types.
It’s likely that cURL’s ubiquity helps sustain its popularity. It comes installed with macOS and is available for Linux and Windows, too. Many public APIs use cURL examples in documentation for easy copy-paste sampling. It’s also a common way for developers to share requests, along with an “it worked on my machine” note.
A more recent alternative to cURL is HTTPie. Also a command line tool, HTTPie is hyper-focused on RESTful APIs returning JSON. Its syntax highlighting and pretty printing of indented JSON make it easier to interpret responses without having to use another tool. For devs intent on working with APIs from the command line, HTTPie is the way to go. But like most high-level languages, there’s some trade-off of convenience over power.
Postman is an API development environment that can be used for making and inspecting API calls. While Postman has always proven useful for solo developers, its newer collaboration features are really where it shines. As you build your API or integrations to other APIs, you can share collections of requests and their responses. Sharing in team workspaces allows you to maintain a single source of truth without sacrificing security. Environments let you share staging and production credentials across the team and still protect sensitive information like personal keys or credentials. In addition, things like syntax highlighting, collapsible JSON, and Hypermedia links are built-in, making it a powerful tool
Receive and Interpret Requests
Whenever you make an API call, someone else receives it. Modern applications should be prepared to be on both sides of these calls. Rather than periodically checking for new data available in an API, you can use event notifications to build more reactive and reliable software. Events are sent through Webhooks - HTTP requests that are sent to a predetermined endpoint.
To set up Webhooks, you first register with a supported API to receive notifications in particular events or on particular resources. Then, when the conditions are met, the service will alert you at a given URL. Webhooks are incredibly useful, but can be difficult to test. You need a server that is set up and ready to accept the notifications. In the process of building, you’ll want a less permanent method to interpret results.
RequestBin is a web frontend service that displays the details of a request. Once you’ve installed your own copy of RequestBin (there’s a deploy to Heroku button), you can begin receiving Webhook requests to a special URL. You can see the full headers, query string, and raw body (with JSON syntax highlighting) to get an idea of what to expect from live Webhooks.
While RequestBin helps you identify what to expect, you still need to translate that to your own code. Again, this can be difficult since Webhooks come through the public Internet, whereas applications usually start on local machines. That’s where SSH tunnels like ngrok and Serveo come in handy. Both of these tools provide a public URL to which you can direct Webhooks. Then, running the tool locally from your command line, you can connect that public URL to your localhost server. With this service, you can write code that reacts to Webhooks. With traffic coming to your local machine, you can make changes and quickly iterate your integration.
Postman offers a robust alternative to tunneling or simply viewing Webhooks. You can use the Postman API to receive Webhooks. Once within the Postman ecosystem, you can extend the request to other Postman features. You can parse a Webhook’s payload and use that data within collections or use the Webhook to kick off monitors (covered in another section below) to test sequences of API calls based on events. Sending Webhooks to Postman allows you to prototype entire software flows without writing any code. Postman proves useful when you need a middle ground between simple review and direct integration with your code.
Create and Use API Descriptions
It’s hard to take a modern API seriously without a machine-readable definition. The most popular specification is the OpenAPI specification. The OpenAPI specification is a format created by a consortium of industry players. It can be used to create documentation, test APIs, and more.
SwaggerHub is an OpenAPI document generator and editor that brings you close to the document itself. It acts like an IDE, suggesting syntax and matching up other resources from your document.
Stoplight provides a visual editor alternative for creating an OpenAPI document from scratch. Rather than hand-code the YAML or JSON files for your API definitions, you can add endpoints in the UI and then export the machine-readable format.
Postman can import and export OpenAPI documents to connect your API to its comprehensive testing and collaboration tools. Postman also has its own format to describe Postman Collections, which go beyond endpoints to include sequences of API calls. When designing APIs, developers can prototype in Collections, share amongst their team, then export the final versions as OpenAPI documents.
With the increasing importance of OpenAPI specs, there will be greater focus on how teams create and use them. Tooling that stays close to a developer’s workflow, rather than focused on the spec that is generated, tends to be more efficient for most teams.
Monitor and Test Your Integrations
Once you’ve built or integrated with an API, you want to make sure it’s working as you expect. Classic uptime monitoring won’t suffice for today’s cloud-connected, integration-dependent world. A simple ping only tells you if a server is up and how quickly it responds. That’s useful, but API monitoring allows for more complex calls and more detailed results.
Simply detecting a response from an API does not tell you whether it returns what’s expected. Your API monitoring tool should include validation of the returned data. Check whether it includes the expected values or the correct number of objects.
Singular API calls rarely stand alone. Typically, API calls are made in succession, where values from one API request are used to seed another. These API call chains mimic the way APIs are really used. Postman monitoring can check single requests or Collections. Whether you’re monitoring your API or an integrated API, it is essential to test all the potential points of failure along this chain—so you can alert your team to react accordingly.
Using monitors in combination with continuous integration and continuous delivery (CI/CD) tools helps ensure your integrations are working as you expect with each deploy. Configure monitoring with Jenkins, Travis, or other CI/CD services already being used by your development teams.
In addition to running tests with each deployment, you’ll want to periodically monitor the APIs you or other API consumers rely upon. Look for flexibility in the timing and location of your monitoring. Some systems should be checked on multiple times per hour, while others don’t need such a watchful eye. Your internal systems might be fine with monitors from a single region. However, if your API is used around the world, you should ensure you have monitors in multiple regions.
Monitors are modern API tooling that makes sure things are still working while you are focused on the next project. They are part of a stack of tools that can help you create and consume better APIs.
Your Modern API Tooling Stack
We’ve mentioned many tools, each useful at some point in the API lifecycle. You can make and inspect API requests as you expand your integrations using cURL, HTTPie, or Postman. You can diagnose issues by receiving and interpreting requests using RequestBin, Serveo, ngrok, or Postman. Swaggerhub, StopLight, and Postman allow you to create and use API descriptions. Finally, you can monitor and test your integrations with Jenkins, Travis, or Postman.
You might have noticed our tool, Postman, shows up in each section. This is because we’ve spent a heap of time building a multi-purpose tool - useful whether designing, accessing, debugging, monitoring, or maintaining an API. Postman has grown from a simple chrome extension into a fully developed platform that supports every stage of the API lifecycle.
It’s natural to be overwhelmed by the variety of API tooling available. Remember, these tools exist to help you create better software more efficiently and more easily. Adopt the tooling that works with your team and can scale with you.