In our interconnected world of microservices, serverless functions and distributed teams, the API is king. In this blog, I’m going to talk about why APIs are essential and demonstrate how you can ensure the reliability of your environment by using the tools provided by Runscope.
What is an API, and Why is it Important?
An application programming interface, or API, is the contract which defines the methods of communication between applications or components. In the past, adding an API to an application was often relegated to the list of tasks to do once development was complete. In modern software development, using an API-First approach allows teams to accelerate development and increase reuse of shared applications and components.
When you build your application based on a well-designed and documented API, you allow other teams the ability to begin integrating their application with yours before development begins. Well-defined APIs allow teams to integrate with your application using the documentation alone.
Key Components for API Management
Your API needs to be available, and it needs to be processing information correctly. You could argue that the second supersedes the first and that all you should do is monitor your API and watch for error cases, but I’ve found it universally true that unreachable APIs don’t generate error logs.
Your comprehensive API management plan should include tests to ensure that the API is reachable by those clients and services which need it and that it processes information appropriately. You should validate the expected use cases, error cases, and edge cases which could include the presence or absence of optional fields and values which approach and exceed any boundaries.
Getting Started with Runscope
I’ve been developing and supporting API-based services for many years, and one of the best tools I’ve found for monitoring and validating my APIs is Runscope. I appreciate the ability to create a test and schedule regular validations of my API within a few minutes. Let me show you how easy it is by demonstrating a simple example.
If you don’t already have a Runscope account, you can sign up for a free trial here. When you sign up, you’ll receive an email with useful resources which include how to import your information from OpenAPI or Postman to create your tests, and how to monitor your APIs from 16 different locations around the globe.
Writing Your First Test
When you first log in to your Runscope account, you’ll be presented with options for different test tutorials. I’d recommend walking through these if you have time, but for this demo, you could also click on the Skip Tutorial button to go directly to the Runscope dashboard.
Figure 1. Welcome to Runscope
The test we're going to create can use any application with an API (one that is accessible from the Internet could be used). The service I’ll be using to demonstrate how to set up a test is one which I deployed temporarily as an AWS service. The test validates that the service accepts a pair of zip codes as part of the URL in an HTTP GET request. The distance between the service is returned in miles as a string without any special formatting.
We’ll begin by logging in and navigating to your Runscope dashboard, clicking on the Create Test option, and selecting New Test.
Figure 2. Creating a New Test from the Dashboard
Enter a meaningful name and a description and click on Create Test.
Figure 3. Enter the Name and Description
We’ll dig into some of the extra features after we get the test running. For the most basic of tests, we’ll enter our GET endpoint in the Steps section under the Request header.
Figure 4. Define the Target for the Request
Next, we’ll click on the Assertions header. There should already be an Assertion which validates that the Status Code for a successful request should be equal to 200. We’ll add another which validates the body of the response for accuracy. In this case, the direct distance between Portland, OR and San Francisco, CA is 533 miles, so I’ll validate that I received that as a response.
Figure 5. Define Assertions for the Test to Pass
Finally, click on the Save & Run option to validate that your test is successful. You can also create a second test to validate a failure option or change the Assertion on the original test to validate that it fails under invalid conditions.
Figure 6. Test Results
That’s all there is to creating a Runscope test. Next, let’s look at additional options for multi-region support, notifications, and scheduling.
Scheduling and Additional Options
If you look under the Environment section and click on Test Settings to expand it, the Locations options should be displayed. You can select from 16 regions around the world from which to run your test. For each location you select, a unique test is run from that location against the endpoint you specified. One of the assertions you can add to your test is response time. Combining locations and response time allows you to monitor the performance of your application from around the world.
The Email Notifications options allow you to select an email address associated with your account, and define the conditions under which you would like to trigger a notification. There are also Integrations provided for use with Slack, PagerDuty, CA API Gateway, DataDog, and there’s the option to create custom Webhooks.
Notifications become especially useful if your tests are running at scheduled intervals. On the left-hand navigation panel, you should have a Schedules link under the Editor option we’ve been using. Schedules are set on a test-by-test basis, and only require a few clicks to enable them. Below, I have my test scheduled to run every minute.
Figure 7. Scheduling Tests
Runscope now takes care of running my tests and notifying me when a problem is detected, thus allowing me to focus on developing new features and better supporting my customers.
If you would like to learn more about adding tests to your Runscope account, including the ability to add authentication parameters, custom assertion logic, and other more advanced features, the Runscope documentation is an excellent source of information.