Runscope API Testing and Monitoring    Learn More →

API Providers: Build a Twilio-like Request Inspector in One Day with Runscope Embeds

By John Sheehan on .

Last week Twilio announced some new developer-focused features for debugging and inspecting the HTTP calls that handle phone calls and messages. The Request Inspector shows you the underlying webhook request and response data that was exchanged during a call flow.

2013-09-21_1554.png

Having complete logs for API and webhook calls available to developers can reduce support times and help developers build their integrations more quickly (closing the deal faster). As we've started to say around Runscope, "If you can't see it, you can't fix it." In our experience, invisibility of problems is the number one barrier to completing an API integration.

A commitment to quality developer experience is what sets apart the great API providers like Twilio and Stripe from everyone else. However, most API providers don't have the resources available to build extensive logging capabilities into their developer portals.  We can help.

Create your own Webhook Request Inspector

rs-dashboard.png

The Runscope Traffic Inspector provides detailed HTTP request and response information for the API calls stored in a bucket. And the best part: it's embeddable with just a few lines of HTML. Combined with our API, you can quickly implement your own request inspector in your portal. 

Below are the high-level steps to follow to build your inspector. Complete technical details can be found in our API docs. We're also standing by ready to answer any integration questions. Feel free to get in touch if you need any help

Step 1: Create a Free Runscope Account

You'll need a free Runscope account to get started. Sign up here

Step 2: Create an Application, Grab Your Personal Access Token

Next you'll need some credentials for calling the API and generating the secure client token required by the embedded HTML. Create an application, then note the Personal Access Token listed on the bottom of the application detail page.

Step 3: Place the Embed HTML and Populate with Client Token

Place the HTML for a 'Stream View' into the necessary place on your site. Full instructions are here. For now, don't worry about the clientToken value.

Step 4: Create Buckets for Your Customers

Buckets are where individual requests are stored. Each embedded stream view gives you a live view of the requests as they are added to a bucket. Using the Buckets resource of the API, you'll want to generate a unique bucket for each developer. Store the bucket key with the developer's account information.

Step 5: Generate a Client Token

In your server-side code you'll need to generate a Client Token that you write out to the page that contains the embed HTML. Don't worry, generating a client token is just a simple POST request. For the bucket_key parameter, use the key you stored in the previous step.

Step 6: Capture the Webhook Request and Response Data

There are two ways to get the webhook request data into the customer's bucket. The first is to use the Messages resource of the API to transfer request and response data from your webhook execution code into the Runscope bucket. This gives you full control over what data is stored. For instance, if you want to omit request or response bodies that contain sensitive data, you can leave that out.

The alternative to injecting data via the API is to make the actual webhook request through a Runscope URL you generate behind the scenes. Learn more about Runscope URLs

In both cases you may want to consider offering the developer the option to temporarily enable the debugger. When the 'debugging mode' is on, store requests in the bucket. When it's off, make them directly without capturing. 

Total time to integration: one work day.

We estimate that it will take a web developer familiar with APIs about a single work day to build a fully-functional, seamlessly-integrated embedded Request Inspector that captures and displays webhook calls in real-time.

Don't use webhooks? You can use these same techniques to build a Request Inspector for regular API calls as well. Get in touch to learn more about your options.

Runscope exists to help developers consuming APIs to quickly solve problems. By using our existing traffic inspection tools you can focus on the value your API provides and complement it with a first-class debugging experience, without a significant investment of time or money.

Categories: howto, testing

Everything is going to be 200 OK®