Runscope API Monitoring    Learn More →

Posts filtered by tag: api

3 Common API Design Errors

3 Common API Design Errors

By Nicolás Bohórquez on .

What does it take to design a good API? Let’s take a look at that question by considering some of the mistakes that developers commonly make when creating APIs.

Error 1: Inconsistent APIs

Consistency could be defined as “agreement or harmony of parts or features to one another or a whole”. When you design an API, it signifies that you keep your decisions aligned to a single line of thought in several aspects.

First, naming conventions […]

Read More →

Categories: apis, design

Quickstart Guide to the Runscope API

By Neil Mansilla on .

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...

Read More →

Categories: apis, product, howto, community

Validating API Payloads Using JSON Schema and Runscope

By John Sheehan on .

Photo of first indoor ice hockey game. (source:  Wikipedia )

Photo of first indoor ice hockey game. (source: Wikipedia)

A popular format for RESTful API schema formats is JSON Schema. It's a well designed spec that is extensible, easy to read and write, and supports canonical and inline referencing/dereferencing. We’ve recently shipped an update that gives Runscope Radar assertion support for JSON Schema validation by way of the Chai assertion library.

So, what exactly does that mean? It means that you’re able to use Runscope API tests to validate your API responses against a defined JSON Schema. A few examples of validation include:

  • insuring method responses are structured properly

  • checking for existence of required keys

  • verifying that values are of a certain type (e.g. integer, string, etc.) and within constraints (min/max)

Runscope API tests currently supports validation against the v4 draft spec of JSON Schema. Let's run through an example.

Step 1: Define the Schema

The method we’re testing pulls down the roster of players on a hockey team. The top level object is an array named roster. Each array item of roster contains an object named player, which has three required properties: player_number, guid and name. So, in this first step, we provide our Runscope test with the JSON schema.

We’ll store the schema as an environment variable via the Initial Script (a script that executes before the request steps begin). At line 1, we’ll store the JSON Schema into a local variable named rosterResponse. In order to make this globally accessible, we’ll store an object using variables.set on line 25. (link to source)

Note: This sample schema uses canonical references (see reference to player object). They're quite handy, especially when you're working in a larger schema with repeated use of an object.

Step 2: Add Request Step and Script Assertion

Our API test has one GET request that returns the team roster. We’ll write our assertion in JavaScript that will validate the response body against the JSON Schema we defined in the previous step.

When we run the test, the results show our schema validation test as passing.

To try this out on your own account, or to read more about JSON Schema and the Chai JSON-Schema module, see the links below:

It's easy to make mistakes when generating a JSON schema. If you need help creating your test objects, check out

If you need assistance setting up validation against your JSON Schema or general help with Runscope contact our support team at any time.

Start monitoring and testing your APIs with JSON Schema validations by starting your free Runscope trial today.

Categories: howto, apis, testing

Runscope 25 Kearny St, 5th Floor San Francisco, CA, 94108 United States

Continuous Integration, Deployment and Testing of Your Web APIs with AppVeyor and Runscope on Azure

By Neil Mansilla on .

Runscope developer advocate Darrel Miller shares a step-by-step instructional blog post on how to integrate AppVeyor (CI tool on Azure) with Runscope to accomplish rock-solid API testing.

Photo by Alex Eylar:

Photo by Alex Eylar:

Fast iterations can be very valuable to the software development process, but make for more time spent doing deployments and testing. Also, more deployments means more opportunities to accidentally introduce breaking changes into your API.

AppVeyor is a cloud based continuous integration server and Runscope enables you to do integration testing of your Web APIs, when these services are combined they can save you time doing the mechanical stuff and ensure your API consumers stay happy.

The following steps show the key points to achieve this integration using AppVeyor, Runscope and Azure websites.

Read the rest of Darrel's post...


Categories: howto, apis, testing

Build a Health Check API for Services Underneath Your API

By Neil Mansilla on .

A  running  cat, in honor of National Cat Day. That's Oskar (click photo for original). Full attribution below.

running cat, in honor of National Cat Day. That's Oskar (click photo for original). Full attribution below.

Monitoring your API's health and performance is something Runscope can do very well. But what about monitoring the underlying services that your API relies on? Databases, like MySQL and Redis, or DNS services on BIND or Mara -- they don't come with RESTful APIs, and in fact, they communicate over lower-level protocols like TCP and UDP. 

When you're relying on services without monitoring, the only time you realize those services are down is when your API (or the apps that rely on your API) go down. Wouldn't it be great if those services had health check API endpoints?

Creating separate health check API endpoints for all services

One approach is to build simple health check API endpoints — a method similar to a ping that reports whether the service is up or down.  Consider building a health check endpoint for every service your backend relies on and using Runscope for testing, reporting and triggering notifications. If you use the same client library or SDK in the health check app that you use for your API backend, you'll have the additional benefit of dependency testing that client library.

That being said, include as few dependencies as possible, isolating the health check app to only what's necessary to connect to the service. I mean, you wouldn’t want a MySQL test to fail because Redis was down. The health check endpoint should do one thing, and one thing only — check that a single service is up and running. If so, return 200. If not, return 503.

MySQL service check example

Below is a pint-sized PHP sample app to test if a MySQL server is up. This app has no library dependencies. It's using PHP's integrated mysqli library. This app can be parked on any web server that can execute/interpret PHP files (e.g. Apache, Nginx, etc.). Ideally, it would be mapped to an endpoint route specifically for health check resources -- but in this example, I've just placed it in the home directory of a vanilla Apache instance. I have MySQL running on another box located on the local network ( and bound to the default port (3306).

  $config = [
     "server"     => “",
     "username"   => "runscope",
     "password"   => "testpass"
  header('Content-type: application/json');

  $link = new mysqli($config['server'],$config['username'],$config['password']);

  if ($link->connect_errno) {
    echo('{ "status": "Unable to connect" }');
  else {
    echo('{ "status": "Connection successful." }');

Ping! Test the endpoint with Runscope Radar Agent

Since my MySQL and Apache servers are behind the firewall, I'll be testing my new health check endpoint with Runscope Radar Agent. This agent will perform tests on the local network and report the results back to Runscope. The only requirement when using the remote Radar Agent is that the computer can make HTTPS requests. Read more about (and download) the Runscope Radar Agent here

After I ran the agent on my local machine (took only a minute to set up), it appeared as a testing location on my Runscope Radar test editor. The location titled Internal-SFO-Office in the screenshot below is my laptop that's running the Runscope Radar Agent.

Runscope Radar Test Editor view. After installing the Runscope Radar Agent on my local machine, it pops up in the list of testing locations.

Runscope Radar Test Editor view. After installing the Runscope Radar Agent on my local machine, it pops up in the list of testing locations.

Next, I clicked Run Now. The MySQL health check test ran from my local Radar Agent. Below were the results from Traffic Inspector.

Setting up notifications

Voilà! The next step would be adding notifications, so that if there is a failure, the correct individual or team could receive email notifications. Additionally, Runscope supports webhooks, so that after tests run, succeed, or fail, Runscope can POST the test result data to any URL. Lastly, if you use PagerDuty, HipChat, Slack, Zapier, etc., Runscope smoothly integrates with all of those services. Read more about notifications here.

Should these be public or private?

You might ask yourself whether these endpoints should be made public or private. The short answer is private. By private, I mean that these should be treated as internal to your company, and not shared with partners or third party consumers of your API. Why? Because the information is too granular and could reveal details about your infrastructure that shouldn't be made public. However, if you were to wrap up all of these micro health checks together, and return a more abstract status response, that would be appropriate as a publicly accessible endpoint.

More micro sample health check apps on GitHub

In addition to the PHP+MySQL sample above, we've built a couple of other examples: Python+Redis, .Net/C#+MS-SQL and Perl+DNS. You're more than welcome to contribute your own. The GitHub repo is located here.

If you need some tips on how to get these health check apps working, or help with setting up Runscope Radar tests against them, our support team is standing by, happy to help.

Cat photo attribution:  LInk to original photo here (Flickr user Tambako). Used under Creative Common license.

Categories: code samples, howto, apis, testing, monitoring

How to Auto-Generate Runscope-powered SDKs for RESTful APIs

By Neil Mansilla on .

The following is a guest post from Adeel Ali from APIMATIC, a company that offers an automatic SDK generator for REST APIs. APIMATIC can import schemas/descriptions of RESTful APIs (WADL, Swagger, I/O Docs, API BluePrint, Google Discovery) and generate SDKs (Android, Windows, iOS, Java, PHP, Python, Ruby, Node.js). Adeel shares an easy to follow guide to building an SDK with APIMATIC and integrating Runscope.


Toward Better SDKs - With APIMatic

SDKs or client libraries are an argumentative topic in the API ecosystem. They are rightly criticized being expensive to build as well as painful to update and maintain. On the other hand, they are considered as crucial, which is evident from the fact that almost all of the top APIs come with SDKs. A closer look at the SDK criticism reveals that the actual pain-point lies in the current development lifecycle of SDKs, and it’s no brainer that if SDK development can be made efficient then it will be a win-win for everyone.

A solution to the above pain-point is replacing the problematic manual development of SDKs by automatic SDK generation. Auto-generated SDKs are cost-effective, easy to update, and offer huge reduction in work-load. is an automatic SDK generator, based in the land of Hobbits with the exact vision of better SDKs. APIMatic was founded in May 2014 by me and Zeeshan, and currently is in public beta phase, that means you can get SDKs for your API in 7 languages for FREE. More about APIMatic can be read in a review by Kin Lane. 

APIMatic & Runscope – A Natural Alliance

We met John Sheehan for the first time last week at APIWorld 2014, where he hinted about embedding Runscope’s API monitoring capabilities in APIMatic SDKs. The idea looked very intuitive because APIs are mostly accessed via SDKs, and by using Runscope powered SDKs, API providers could inspect/debug all of the request and response data traveling back and forth from the clients using their SDKs. The amount of convenience could be assessed by the fact that setting a single flag would automatically enable API debugging capability in SDKs in 7 languages (to date), while no settings would be required at the client side.

The idea has now become a reality, and in the remaining of the post I am going to show how you can generate Runscope powered SDKs.

Runscope Powered SDKs – Step by Step

Step 1
Create a Runscope bucket, and copy the bucket key. 

Step 2
Specify an API description at APIMatic. The two ways to do it are: importing an API description, or describing an API from scratch. I am describing Vimeo’s public API from scratch here, and will only be specifying two end-points to keep the demo simple. 


Step 3
Go to CodeGen Settings and enter the obtained Bucket Key from Runscope. Save the settings.


Step 4
Once the API is defined, go back to the API list, and click the validate button to validate the API description.

Step 5
If all is well, you will be presented with icons of different languages to generate SDKs. Choose your favourite language, and click the icon to download the SDK in a ZIP file.

Step 6
Unzip the contents of the downloaded SDK and open the Configuration file to provide your credentials to access the API. The contents of a generated C# Portable Class Library can be seen in the following snippet. It can be noticed in the Configuartion.cs file that the BaseUri has been transformed to the Runscope-desired format. If you are not using an interpreted language, you’ll now need to compile the SDK to get a compiled binary. There is a ReadMe file in the root folder file if you need any assistance.


Step 7
Now you have a (compiled) library in your hands which you can reference in an application. Here I am referencing and using the .dll file obtained from the previous step in a simple application. This application searches for videos on Vimeo against a provided keyword, and shows the total number of videos found as the result. The code to access the API functions via SDK can be seen in the snippet below.

Step 8
Go back to the Runscope portal, and select your bucket from the top left corner. You can watch all of the API traffic initiated by your app. The summary of the API calls originated by my application can be seen in the following snippet. Click on any particular call to see a detailed record, compare requests or responses, or play around with the other available options at a very friendly portal.


That’s it!

Congratulations on generating your first Runscope powered SDK. I love hearing feedback, so please comment on the post, or send me an email. If you need any assistance, don’t hesitate to ask. 

Categories: code samples, howto, apis

Everything is going to be 200 OK®