Importing Swagger, RAML, Postman, and HAR API Representations to Create API Monitors

The importance of APIs (Application Programming Interfaces) continues to grow, as established and start-up vendors recognize their utility both as the foundation of their own products and as a means by which they can sell their services to other companies as components of new products. Because of this, publishing representations of APIs has gained currency: if you want to sell the services you provide to other companies, you need to provide them with a standardized view into the interface your API provides.

Presently, there are multiple platforms for publishing API representations. These include:

  • Swagger – a project that provides “a simple yet powerful representation of your RESTful API”;
  • RAML – the RESTful API Modeling Language;
  • Postman – a platform that lets you construct and document API requests and workflows;
  • HAR – the World Wide Web Consortium’s HTTP Archive format.

If your own product uses internal or external APIs, you’ll want to monitor the uptime and performance of those APIs. If the APIs that are critical to your product have a Swagger, RAML, Postman, or HAR representation, you can easily create a monitor for those APIs using API Science’s Import capability:

import-page

In this post, I’ll detail how to create API monitors by importing API representations developed using these platforms.

 

Swagger

Swagger is an open source project that bills itself as “the World’s most popular framework for APIs”:

Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.

Swagger’s Getting Started page states that Swagger’s goal “is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.”

Swagger provides the Swagger Petstore API as an example of its API representation capabilities. We’ll use this to create our API Science monitor.

Creating the API Science Monitor

To create a Swagger Petstore API monitor, log into your API Science account, click “Import” at the top of the page, and scroll down to the “Swagger” section:

swagger-import

Click the “Import From Swagger” button, and enter the Swagger Petstore API URL:

swagger-import-url

Clicking the “Import” button embeds the Swagger summary page for the Swagger Petstore API:

swagger-petstore-import

Let’s say your product depends on information about the Pet Store’s pets. Clicking on the pet link displays the available API calls related to pets:

swagger-pet-store-api-calls

Futhermore, let’s say your product depends on getting information about specific pets based on the petID. Clicking on “GET /pet/{petID}” link brings up the details:

swagger-petstore-import-get-petid

Entering an integer (for example, 1) into the petId field and clicking the “Try it out!” button produces a result like this:

swagger-petstore-import-get-petid-result

Clicking the “Run on API Science” button creates your new API Science monitor, runs the monitor, and provides you with its URL:

swagger-petstore-import-apiscience-url

Your API Science dashboard now includes the new monitor:

swagger-petstore-api-science-dashboard1

Clicking on the monitor name shows you the first result from your new API Science API monitor check:

swagger-petstore-api-science-checks1

So, in a few simple steps, we’ve taken a Swagger API definition and turned it into an API Science monitor.

 

RAML

The point of RAML (the RESTful API Modeling Language) is to make it “easy to manage the whole API lifecycle from design to sharing.” In this example, we’ll use the API Science Facebook RAML API specification to create a new monitor.

To get started, log into your API Science account, and click the “Import” link at the top of the page:

api-science-home-page-menus

Scroll down to the “RAML” section and click the “Import From RAML” button:

import-from-raml-button

The API Science Facebook RAML specification is available as a URL, so in this case we select the “Import from URL” tab:

raml-import-facebook-url

Here’s what this RAML file looks like:

#%RAML 0.8
title: Facebook Graph API
baseUri: "https://graph.facebook.com"
"/{node}": 
  uriParameters:
    node:
      description: "Details for node (ex: a user, group, page)."
      type: string
  get:
    description: "Get a single node."
    responses:
      200:
        body:
            application/json:

Clicking the “Import” button brings us to the import Facebook Graph API page:

raml-facebook-graph-api

Clicking the “GET” tab opens a detailed view of the API:

raml-facebook-graph-api-detail

Entering a “node” value is required. If you enter a node, then you can click the “GET” button to retrieve the normal response to the request (assuming the API is currently up). Here’s the upper portion of the result when I enter “whitehouse” in the “node” field and click the “GET” button:

raml-facebook-graph-response-top

Clicking the “Monitor on API Science” button creates your API Science monitor for the Facebook Graph API:

raml-facebook-graph-monitor-created

Clicking the link beneath “New Monitor Created” brings you to the summary page for your new API Science Facebook Graph API monitor:

facebook-graph-monitor-summary

We’ve now created a new API Science monitor by importing a RAML file from a URL.

 

Postman

Postman is a platform that enables you to construct API requests and workflows, test integration suites, document your work, and share your finished product with your team and others. The fundamental building block for a Postman application is a “collection” — which consists of one or more API requests, and scripted actions based on the response each request returns.

Postman is available as a Chrome app, but the Postman team recommends the more powerful native apps, which are available for Mac, Windows, and Linux (Beta). In the following examples, I used the Windows native Postman app. I downloaded this from the Postman Apps page, ran the installer, and launched the Postman application:

postman-app

Now we’re ready to use the Postman Builder to create a request.

Let’s say we’d like to query the World Bank’s Countries API for information about Canada. The World Bank Countries API supports two- and three-letter ISO codes. The two-letter ISO code for Canada is CA. Based on this, we can create a World Bank Countries API GET request using this URL:

http://api.worldbank.org/countries/ca

Entering this into the Postman “Enter request URL” field and clicking the “Send” button produces this result:

postman-world-bank-ca-response

The GET query succeeded: the World Bank Countries API responded by sending the information about Canada, including region, income level, capital, etc.

Let’s assume your company’s product is focused on providing information about the state of the Arctic Ocean, and you use the World Bank information about the nations that have coastlines on the Arctic Ocean. How can you know when that information is available, and when it is not available? If the World Bank Canada information is not available, your product/app may appear “down” to your users. In any case, if this API is a component of your product, you will want to know when, and how often, the API is down, or when its performance is poor.

This is the type of information that is provided to you by your API Science account.

So, having successfully created your Postman test request, how do you turn this into an API Science monitor?

First, click that “Save” button on the Postman result window. This results in a pop-up that lets us enter a description of this request and either add it to an existing Postman “collection” or create a new one:

postman-world-bank-new-collection

In this case, I’m creating a new Postman collection named “World Bank Arctic Countries.” Clicking the “Save” button accomplishes this.

Next, you can export your Postman collection. From our Collections tab, we click the “…” next to our “World Bank Arctic Countries” collection, and this raises a pull-down menu that includes an “Export” option that lets us save our Postman collection to a file:

postman-collection-export-menu

Now, go to your API Science Dashboard, click “Import” at the top of the page, then click the “Import From Postman” button:

postman-import

In this case, we exported our Postman collection to a file. So, we click the “Import from File” tab then click the “Browse” button:

import-postman-file

Select the file you exported from Postman, and click the “Create Monitors” button:

postman-import-create-monitors

This brings us to our API Science Dashboard, which now includes the new monitor GET http://api.worldbank.org/countries/ca (the monitor name is editable). Clicking on the monitor brings up our first check page:

postman-import-first-monitor-check

We’ve now created an API collection in Postman, imported it into our API Science account, and created a monitor that will let us assess this API’s performance and uptime, and alert our team should the API go down.

 

HAR

The HTTP Archive (HAR) format is a JSON file format that records the interactions between a web browser and web pages. HAR files can be used, for example, as a means for customers to record interactions with a web service, to record recurring problems and send them to a troubleshooting team.

The HAR format can also record the interactions that occur when a request is sent to an API. In this example, I illustrate how to create an HAR file that queries the World Bank Countries API. Then, I’ll import the HAR file into my API Science account to create a new World Bank API monitor.

Creating the HAR File

Wikipedia notes that various software supports the creation of HAR files. In this demonstration, I’ll use Chromium Version 49.x running on Ubuntu Linux.

If your product is related to the Arctic Ocean, it might query the World Bank Countries API for information about the Russian Federation. The API endpoint for this request is: http://api.worldbank.org/countries/ru

Entering this URL into a browser produces a response web page like this:

world-bank-ru-web-view

Chromium includes a “Developer Tools” menu, that appears in different locations depending on the Chromium version and how you’ve configured your browser. In my case, clicking the three bars in the upper right corner of the browser window creates a pop-up menu that includes a “More tools” item. Clicking on this brings up a sub-menu that includes a “Developer tools” item. That item, in my case, includes the hint that the keyboard shortcut Ctrl+Shift+I will also bring me to the Developer tools panel.

Here’s what it looks like:

chromium-developer-tools-panel

I click the red circle at the upper left to initiate recording, and check the “Preserve log” item in the middle of the same row so that a log of all events will be created.

Next, in the browser’s URL entry field, I paste in the World Bank Countries API URL for the Russian Federation, and press “Enter” to initiate the request. Here is a typical result from my experiments:

chromium-world-bank-ru-recording

Now, we need to save the web activity as a HAR file. To do this, right-click the “ru” entry under the “Name” column at the lower right of the page. This will create a pop-up menu that has options including Copy All as HAR and Save. In the first case, you’ll have to create a text file, then you’ll paste in the stored request, the response results, and corollary data; in the second case, you’ll be prompted to enter a file name in which much-reduced information will be stored. Both HAR formats can be imported into your API Science account.

Using the HAR File to Create an API Science Monitor

Using the Chromium developer tools Copy All as HAR option, I created a HAR file named World_Bank_ru.har. Having stored that HAR file locally, I can now go to my API Science account and import the file to create a new API monitor.

Click “Import” in the top menu bar, scroll down to “HAR (HTTP Archive 1.2)”:

import-from-har-button

Clicking the “Import From HAR” button brings up the HAR Import page:

har_import_page

Since I’ve stored my HAR data as a local file, I click the “Import from File” tab, then click the “Browse” button to select the file. In the “File Upload” window that pops up, I navigate to my HAR file, select it, and click the “Open” button:

har-file-select1

Clicking the “Open” button brings this file into our API Science account, detects the API’s GET URI, and presents a page that enables us to create a monitor based on this:

har-import-uri-selection

Check the presented GET command and click the “Create Monitors” button to generate your new API monitor.

We’re brought to our API Science Dashboard, which now includes a new monitor named:

GET http://api.worldbank.org/countries/ru

Clicking this monitor’s name brings us to the new monitor’s summary page:

har-import-first-api-check

The first API check has been run, and this instance succeeded.

We’ve now utilized the Chromium web browser to create an HTTP Archive (*.har) file based on navigating to a web page; then we’ve imported that HAR file to automatically create an API Science monitor that will regularly check the status of calls to that API.

 

Conclusion

For any API that is a critical component of your product — whether the API is internal or external — if the API has a Swagger, RAML, Postman, or HAR representation, it is possible for you to easily and quickly create an API Science monitor that checks and logs the API’s current status, and notifies your team in an emergency wherein that API being down makes your customers see your own product as being down.

And you know your customers will go elsewhere if they find your product to be down too many times when they need or want it — don’t you?

–Kevin Farnham