Intro To API's

Intro

The Application Programming Interface is how code/computers talk to each other, and provides an easy way to collect data or services from external sources.

There is a directory of available API’s at: Programmableweb.com

When you make a request to an API, it is similar to making a request to a website. When you make an HTTP request the website sends back HTML, which is data and structure. When we make an API request, the API responds with just data. That data uses a simpler format than HTML. Typically XML or JSON.

XML

XML is syntactically similar to HTML, but does not describe structure or presentation.

<bird>
    <species>Toucan</species>
    <color>Black</color>
    <location>South America</location>
</bird>
<bird>
    <species>Condor</species>
    <color>White</color>
    <location>Africa</location>
</bird>

JSON

JavaScript Object Notation. JSON is syntactically similar to Javascript Objects, but everything is a string.

{
  "bird": {
    "species": "Toucan",
    "color": "Black",
    "location": "South America",
  }
}

Endpoint

The endpoint is the URL that you make an API request to.

Making API Requests

API Requests with Curl

Curl is a terminal command that can be used to make requests in the terminal. You can make both HTTP and API requests using this command. Though it would be less common to make an HTTP request in your terminal since the terminal won’t actually render a page, we can do it.

curl www.google.com

However this will return an incoherent mess of html.

API Requests with Node

To make requests with a Node server you will want to download a package to help with this. The most common is called request.

request()

The primary function this package provides is request(uri, options, callback) and the callback consists of function(error, response, body).

Here is the official sample code:

var request = require('request');
request('http://www.google.com', function (error, response, body) {
  console.log('error:', error); // Print the error if one occurred
  console.log('statusCode:', response && response.statusCode); // Print the response status code if a response was received
  console.log('body:', body); // Print the HTML for the Google homepage.
});

In it’s simplest form you can think of the request like this:

request( what I want, what to do with it )

Most API’s these days require authentication, which is a subject we will get to later. But to get started we want to use API’s that do not require anything more than the request URL. There is an excellent list of API’s available on Github.

We will use the Star Wars API (SWAPI) for our examples. Let’s request all the data available on the planet with id=1

request('http://swapi.co/api/planets/1/', function (error, response, body) {
  console.log('error:', error); // Print the error if one occurred
  console.log('statusCode:', response && response.statusCode); // Print the response status code if a response was received
  console.log('body:', body); // Return JSON string of body content
});

Which returns and logs the following in the console

error: null
statusCode: 200
body: {"name":"Tatooine","rotation_period":"23","orbital_period":"304","diameter":"10465","climate":"arid","gravity":"1 standard","terrain":"desert","surface_water":"1","population":"200000","residents":["https://swapi.co/api/people/1/","https://swapi.co/api/people/2/","https://swapi.co/api/people/4/","https://swapi.co/api/people/6/","https://swapi.co/api/people/7/","https://swapi.co/api/people/8/","https://swapi.co/api/people/9/","https://swapi.co/api/people/11/","https://swapi.co/api/people/43/","https://swapi.co/api/people/62/"],"films":["https://swapi.co/api/films/5/","https://swapi.co/api/films/4/","https://swapi.co/api/films/6/","https://swapi.co/api/films/3/","https://swapi.co/api/films/1/"],"created":"2014-12-09T13:50:49.641000Z","edited":"2014-12-21T20:48:04.175778Z","url":"https://swapi.co/api/planets/1/"}

It’s not formatted nicely, but you can see that we got null for errors, a response code of 200 which is the standard code for success, and we got back a string with data about Tatooine. Nice.

Parse String to JSON Object

Getting the data in the body back is great, but it is all in a string, which makes it difficult for us to pull out parts of that data. What we need to do is parse the data into a JSON Object, and we can do that using Javascripts built in JSON function.

JSON.parse(body);

and we can set that to a variable and then log the variable

request('http://swapi.co/api/planets/1/', function (error, response, body) {
  console.log('error:', error); 
  console.log('statusCode:', response && response.statusCode); 
  
  var parsedBody = JSON.parse(body);
  console.log(parsedBody);

});

Which then returns a nicely formatted JSON Object

error: null
statusCode: 200
{ name: 'Tatooine',
  rotation_period: '23',
  orbital_period: '304',
  diameter: '10465',
  climate: 'arid',
  gravity: '1 standard',
  terrain: 'desert',
  surface_water: '1',
  population: '200000',
  residents:
   [ 'https://swapi.co/api/people/1/',
     'https://swapi.co/api/people/2/',
     'https://swapi.co/api/people/4/',
     'https://swapi.co/api/people/6/',
     'https://swapi.co/api/people/7/',
     'https://swapi.co/api/people/8/',
     'https://swapi.co/api/people/9/',
     'https://swapi.co/api/people/11/',
     'https://swapi.co/api/people/43/',
     'https://swapi.co/api/people/62/' ],
  films:
   [ 'https://swapi.co/api/films/5/',
     'https://swapi.co/api/films/4/',
     'https://swapi.co/api/films/6/',
     'https://swapi.co/api/films/3/',
     'https://swapi.co/api/films/1/' ],
  created: '2014-12-09T13:50:49.641000Z',
  edited: '2014-12-21T20:48:04.175778Z',
  url: 'https://swapi.co/api/planets/1/' }

Refining The Request

Now we can start to pull specific pieces of information out of the response. If we wanted to get just the name and climate we would log the following

console.log(parsedBody["name"]);
console.log(parsedBody["terrain"]);

we would get back

Tatooine
desert

Sub-Categories

If the data was organized into subcategories we can refine our request by chaining the keys. In this sample we will request the titles of all the movies, and then the first movie title (index 0).

request('http://swapi.co/api/films/', function (error, response, body) {
  console.log('error:', error); 
  console.log('statusCode:', response && response.statusCode); 
  
  var parsedBody = JSON.parse(body);
  
  console.log(parsedBody["results"][0]["title"]);
  
});

A New Hope

or if we wanted to loop over the results array and print all the titles we could do the following

for(var i=0;i<parsedBody["results"].length;i++){
  console.log(parsedBody["results"][i]["title"]);
  }

A New Hope
Attack of the Clones
The Phantom Menace
Revenge of the Sith
Return of the Jedi
The Empire Strikes Back
The Force Awakens

Github Repo

Ncoughlin: API-practice

Comments

Recent Work

Basalt

basalt.software

Free desktop AI Chat client, designed for developers and businesses. Unlocks advanced model settings only available in the API. Includes quality of life features like custom syntax highlighting.

Learn More

BidBear

bidbear.io

Bidbear is a report automation tool. It downloads Amazon Seller and Advertising reports, daily, to a private database. It then merges and formats the data into beautiful, on demand, exportable performance reports.

Learn More