Search results

Inspect the JSON from the response payload

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

Seeing the response from curl or Postman is cool, but how do you make use of the JSON data? With most API documentation, you don’t need to show how to make use of JSON data. You assume that developers will use their front-end development skills to parse through the data and display it appropriately in their apps. However, to better understand how developers will access the data, we’ll go through a brief tutorial to display the REST response on a web page.

Activity: Make the request on a page with AJAX

For this activity, you’ll use JavaScript to display the API response on a web page. You’ll use some auto-generated jQuery code from Postman to create the AJAX request.

  1. In a text editor (such as Sublime Text), create a new HTML file and paste in the following boilerplate template (which contains basic HTML tags and a reference to jQuery):

    <html>
    <meta charset="UTF-8">
      <head>
          <title>Sample page</title>
          <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
      </head>
    <body>
      <h1>Sample page</h2>
    
    </body>
    </html>
    
  2. Save your file (anywhere convenient) with a name such as weather.html.

  3. Open Postman and go to the Current weather data (weather) endpoint that you configured in an earlier activity (see Submit requests through Postman.
  4. Click the Code link (below the Save button), and then select JavaScript > jQuery AJAX.

    JavaScript Ajax code snippet

    The AJAX code should look as follows:

    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial",
      "method": "GET",
      "headers": {
        "cache-control": "no-cache",
        "postman-token": "e9be9756-b922-89b3-7109-66bc4cf06b17"
      }
    }
    
    $.ajax(settings).done(function (response) {
      console.log(response);
    });
    
  5. Click Copy to Clipboard to copy the code sample.
  6. In the same template you started building in step 1, add a pair of <script></script> tags below the jQuery reference, and then insert the Postman code inside your script tags.
  7. In the jQuery code, remove the headers object that Postman inserts:

    "headers": {
      "cache-control": "no-cache",
      "postman-token": "e9be9756-b922-89b3-7109-66bc4cf06b17"
    }
    
  8. Also remove the comma after "method": "GET".

    Your final code should look like this:

    <!DOCTYPE html>
    <html>
       <meta charset="UTF-8">
       <head>
          <meta charset="UTF-8">
          <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
          <title>Sample Page</title>
          <script>
             var settings = {
               "async": true,
               "crossDomain": true,
               "url": "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial",
               "method": "GET"
             }
    
             $.ajax(settings).done(function (response) {
               console.log(response);
             });
          </script>
       </head>
       <body>
          <h1>Sample Page</h1>
       </body>
    </html>
    

    You can view the file here: idratherbewriting.com/learnapidoc/assets/files/weather-plain.html

  9. Start Chrome and open the JavaScript Console by going to View > Developer > JavaScript Console.
  10. In Chrome, go to File > Open File and select the weather.html file. (If you don’t see the File menu in Chrome, press Cmd + O or Ctrl + O, or just drag your weather.html file into your browser window.)

    The page body will be blank, but the weather response should be logged to the JavaScript Console (due to the console.log(response) code in the request). If you expand the object returned to the console, it will look as follows:

    JSON payload from weather API logged to console

    This information is now available for you to integrate into your page.

The AJAX method from jQuery

In this section, I’ll explain a bit more about the ajax function you used earlier. This information probably isn’t essential for documenting REST APIs, but it’s good to understand. To recap, here’s the ajax script:

<script>
   var settings = {
     "async": true,
     "crossDomain": true,
     "url": "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial",
     "method": "GET"
   }

   $.ajax(settings).done(function (response) {
     console.log(response);
   });
</script>

If you’re working with JavaScript and APIs, the ajax method from jQuery can be helpful with code samples. This ajax method takes one argument: settings.

$.ajax(settings)

The settings argument is an object that contains a variety of key-value pairs.

var settings = {
}

Each of the allowed key-value pairs is defined in jQuery’s ajax documentation.

Some important values are the url, which is the URI or endpoint you are submitting the request to. Another value is headers, which allows you to include custom headers in the request.

Look at the code sample you created. The settings variable is passed in as the argument to the ajax method. jQuery makes the request to the HTTP URL asynchronously, which means it won’t hang up your computer while you wait for the response. You can continue using your application while the request executes.

You get the response by calling the method done.

$.ajax(settings).done(function (response) {
})

In the earlier code sample, done contains an anonymous function (a function without a name) that executes when done is called. The response object from the ajax call is assigned to the done method’s argument, which in this case is response. (You can name the argument whatever you want.)

You can then access the values from the response object using object notation. In this example, the response is just logged to the console.

If you’re new to JavaScript, this is likely a bit fuzzy right now. If so, don’t worry — code becomes clearer the more you use it.

Notice how difficult it is to explain code? This is one of the challenges of developer documentation. Fortunately, you wouldn’t need to explain much from standard programming languages like JavaScript. But you might need to explain how to work with your API in different languages. I cover this topic in more depth in Code samples and tutorials.

Logging responses to the console

The piece of code that logged the response to the console was simply this:

console.log(response);

Logging responses to the console is one of the most useful ways to test whether an API response is working (it’s also helpful for debugging or troubleshooting your code). The console collapses each object inside its own expandable section. This allows you to inspect the payload.

You can add other information to the console log message. To preface the log message with a string, add something like this:

console.log("Here's the response: " + response);

Strings are always enclosed inside quotation marks, and you use the plus sign + to concatenate strings with JavaScript variables, like response.

Customizing log messages is helpful if you’re logging various things to the console and need to flag them with an identifier.

Inspect the payload

Inspect the payload by expanding each of the sections returned in the JSON console object. Based on the information here, what’s the forecast for today?

I realize the page is blank and unexciting. In the next section, Access and print a specific JSON value, we’ll pull out some values and print them to the page.

21% Complete

21/110 pages complete. Only 89 more pages to go...

Donate?

Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.