This is part one of a series of blog posts about how to use the Runscope API. In this article you’ll learn how to get started using the API in less than 5 minutes, from creating your first access token to fetching the tests in your bucket.
The Runscope API provides access to the data within your Runscope account. This includes access to read, create, modify and delete nearly every type of resource — from tests, environments, schedules, test results, request logs to buckets. The API makes Runscope incredibly pliable, helping Runscope to fit into how your team develops, tests and deploys software.
We know that getting started with new APIs can sometimes be daunting. But rest assured, if you're even lightly familiar with Runscope, you'll be making API calls in five minutes or less -- all from within Runscope, no tools or coding required.
Step 1: Create an app and access token
Our API uses the OAuth 2.0 protocol for authentication. If you've ever used APIs from GitHub, Twitter, Facebook or Google, then you're already familiar with this first step -- you need create an Application. When an Application is created, a personal access token that's authorized to access data in your account is conveniently generated. Using this token you can begin making API calls immediately without having to step through the account authorization flow.
Step 2: Start with your bucket list
All of your tests, environments and logged API traffic are organized into Buckets. Every API method related to managing API tests and logged traffic requires a bucket key. Therefore, the first API call to try is Bucket List method. When you make a GET call to the /buckets endpoint, a list of buckets is returned in the data array.
In order to make an authenticated request to the Runscope API, the access token is passed in the Authorization header. The auth header is pre-populated when you click Try it in the Request Editor button.
Note: bucket keys are unique resource IDs. Bucket key values do not change after a bucket is created and are safe to cache. Bucket names, however, are not guaranteed to be unique (you can have two buckets with the same name).
Step 3: Fetch your tests
Next, try the Test List method. This method lists all of the tests that reside in the specified bucket. Similar to the Bucket List method, a list of tests is returned in the data array. In the screencast below, we’re listing out all of our tests, and then making another call to fetch a specific test using the Test Detail method.
The amount of information returned may at first seem a bit overwhelming; however, if you look closely, you’ll find that it’s rather easy to understand with object key names that intuitively map back to the Runscope UI.
Exploring other methods and resources
Use the List Buckets and List Tests methods above to familiarize yourself with the JSON representation of the Runscope data that you regularly manage in the dashboard UI. Now that you know how easy it is to get started, we encourage you to try out other methods and resources. While you're still learning how to use the API and trying out new methods, we suggest that you create a new bucket that acts as a sandbox, or stick with read-only (GET) methods if you're making calls against production-level buckets/data.
In the follow up articles in this series, we'll dig deeper into the anatomy of the Test Resource (steps, assertions, environments, etc.) as well as how to create new and modify existing tests. Soon enough, you'll feel as comfortable working with Runscope through the API as you do through the UI. Meanwhile, if you need any help navigating the API, check out the API Documentation or contact our Support team.
Original photo by Oscar Rethwill under CC License.