A 5 Minute Crash Course on APIs

What exactly is an API? API stands for Application Programming Interface, and simply put, it allows your application to work with other applications, usually in the form of JSON data.

Let's say that you wanted your web application to pull in data from a source like Wikipedia. With an API, you can programatically pull the information right from Wikipedia, and format it to fit your site nicely, only showing the information that you want.

For this example, our website wants to pull in Wikipedia articles about the New England Patriots.

First, let's setup our API endpoint.

var url = "https://en.wikipedia.org/w/api.php?action=query&origin=*&format=json&generator=search&gsrnamespace=0&gsrlimit=5&gsrsearch='New_England_Patriots'";

To learn more about creating your Wikipedia API endpoint, visit the Wikipedia API docs: https://www.mediawiki.org/wiki/API:Query.

Don't worry too much about the details of URL above right now. Click here to see what our endpoint actually looks like.

NOTE: Include the &origin=* parameter in your endpoint to prevent any CORS issues.

Next we need to setup a way to communicate with Wikipedia's server.

There's a few ways to do this. In this example we will be using an XMLHttpRequest, which despite the name, can be used for more than just XML data. XMLHttpRequest's allow you to retrieve data from a server without needing to refresh the page and they're very popular in Ajax programming.

var xhr = new XMLHttpRequest();

Open up our connection to the server

// Open a new connection, using the GET request on the URL endpoint
// Providing 3 arguments (GET/POST, The URL, Async True/False)
xhr.open('GET', url, true);

Once we've retrieved our XML Request, convert it to JSON

JavaScript Object Notation, or JSON for short, is a really handy way to to send, receive, and access complex data objects.

Read more about JSON here on the Mozilla Developer Network

// Once request has loaded...
xhr.onload = function() {
    // Parse the request into JSON
    var data = JSON.parse(this.response);

    // Log the data object
    console.log(data);

    // Log the page objects
    console.log(data.query.pages)

    // Loop through the data object
    // Pulling out the titles of each page
    for (var i in data.query.pages) {
        console.log(data.query.pages[i].title);
    }
}

Send the HTTP response asynchronously

// Send request to the server
xhr.send();

Entire Code Snippet

And that's all there is to it! If everything worked correctly, we should our application should log 5 Wikipedia article titles about the New England Patriots to our browser console. Try messing around with the New_England_Patriots part of the API endpoint and see what happens. You can also try dynamically changing this part of the endpoint to populate something that a user types in to an input field if you're feeling daring.

var url = "https://en.wikipedia.org/w/api.php?action=query&origin=*&format=json&generator=search&gsrnamespace=0&gsrlimit=5&gsrsearch='New_England_Patriots'";

//Create a new object to interact with the server
var xhr = new XMLHttpRequest();

// Provide 3 arguments (GET/POST, The URL, Async True/False)
xhr.open('GET', url, true);

// Once request has loaded...
xhr.onload = function() {
    // Parse the request into JSON
    var data = JSON.parse(this.response);

    // Log the data object
    console.log(data);

    // Log the page objects
    console.log(data.query.pages)

    // Loop through the data object
    // Pulling out the titles of each page
    for (var i in data.query.pages) {
        console.log(data.query.pages[i].title);
    }
}
// Send request to the server asynchronously
xhr.send();

Try this the code in your browser console.