Playing fetch() with my API

Introduction

The first time you use fetch() to get data from a server is like kissing a girl for the first time. The whole experience is shrouded in mystery and wonder. It is a rite of passage. An important step to becoming a man. Poets and singers have spent a lifetime exploring the topic. But this is not that type of tutorial...

This is however an important step to becoming a real programmer. And it is a topic you will keep exploring and coming back to.

So to quote The Little Mermaid : You gotta kiss the girl... And I am going to show you how.

API? what the #$%@!?

An API application user interface!? is one of those elusive terms we all use without actually knowing what it is. When people are asked exactly what it is they tend to give vague general explanations. So who am I to break with tradition?

For our purposes just think of an API as a waiter at your favourite restuarant. You decide what you want to order off the menu. Then you give your order to the waiter (our API) and the waiter gives the order to the kitchen. Then when the order is ready the waiter (API) fetches your order and brings it to your table.

Now that you have your food you can decide how you want to consume it (or display and process it).

Fetch boy!

So now we have our robot waiter eager to take our order. But how do we tell it to fetch our order?

The answer is surprisingly simple. We just tell it fetch()!

And yes it really is that simple.

Take a look at this code. The code has been simplified for your convenience.

    fetch(URL)
        .then()
        .then()
        .catch()

So basically you tell the API to fetch whatever is at the URL. Then you wait. The then()'s are attached to the fetch method because this process happens asynchronously (means it takes some time to complete).

So you are telling the API: "Ok go and place my order. Then when it is ready bring it back."

The catch() at the end is to catch any errors.

Let us take a look at each of these methods in turn.

Here you wait for the response to return and then convert it into json format.

    fetch()
        .then(response => response.json())
        .then()
        .catch()

Here we display the data object by extracting the properties on the json object. There are different ways of performing this step. Remember this is a simplified version so you can get the bigger picture.

    fetch()
        .then()
        .then(data => {
            display(data.properties);
        })
        .catch()

The last step is to catch any errors that might result.

    fetch()
        .then()
        .then()
        .catch(error => {
            console.log(error)
        })

Now that we got the basics out of the way let's go ahead and kiss that girl.

Finding an API

Finding that right API can be a little tricky. And in most cases you will need to jump through a couple of hoops to get access to the API and then there will likely be some restrictions and small print and and...

Luckily this kind person, Ana Kravitz, founder of Mixed Analytics, has provided us with some free no-nonsense APIs for us to practice with. I have picked one from the list and I will show you how to use it. Then you can try out some on your own and leave a link to your code in the comments section so I can give it a big Thumbs Up!!!

For this tutorial I selected number 19 from the list. It is simply called JokeAPI. I copied the link and stored it in a variable like this:

    const jokes = 'https://sv443.net/jokeapi/v2/joke/programming';

Then I told our API to fetch the data for me and I waited for a response. I then converted the response to json and logged the data to the console so I could see what I was working with.

    fetch(jokes)
        .then(response => response.json())
        .then(data => {
            console.log(data);
        });

What you get returned is basically a javaScript object. It looks something like this:

{category: "Programming", type: "twopart", setup: "So what's a set of predefined steps the government might take to preserve the environment?", delivery: "An Al-Gore-ithm.", flags: {…}, …}
    category: "Programming"
    delivery: "An Al-Gore-ithm."
    error: false
    flags:
    nsfw: false
    political: false
    racist: false
    religious: false
    sexist: false
__proto__: Object
id: 52
setup: "So what's a set of predefined steps the government might take to preserve the environment?"
    type: "twopart"
__proto__: Object

Don't panic! It is not as bad as it looks. All we are really concerned about here is the object returned to us.

This API returns two types of joke objects. An object with type 'single' or an object with type 'twopart'.

So we will need to find a way of knowing what type of object we will be dealing with.

First let's take a simple view of these two different types of objects. When you are working with your own API you will need to do a little exploring to find out the nature of the objects returned.

Type Single Object

    {
      type: "single",
      joke: "...funny joke goes here"  
    }

Type Twopart object

    {
      type: "twopart",
      setup: "...a question or some scenario",
      delivery: "...the punchline"
    }

You can see that the objects both have a property of type. One with the value 'single' and the other a value of 'twopart'.

So we will use an if statement to determine the type of object we are working with and then access the appropriate properties on each object like this. Remember we get a data object returned to us in the second then().

    fetch(jokes)
        .then(response => response.json())
        .then(data => {
            if (data.type  == 'single'){
                console.log(data.joke);
            }
            if (data.type == 'twopart'){
                console.log(data.setup);
                console.log(data.delivery);
            }
        });

So now no matter the type of object returned to us we will still be able to view the joke in the console. All we need to do now is slap on the catch() to catch any errors and Bob's your uncle.

But viewing jokes in the console is not much fun. Let me show you how we can set up the API to view the jokes on the page. Maybe with a button you can press to update the joke.

The full javaScript code

const jokes = 'https://sv443.net/jokeapi/v2/joke/programming';
const btn = document.querySelector('.w3-button');
btn.onclick = () => {
    fetch(jokes)
        .then(response => response.json())
        .then(data => { 
            if (data.type  == 'single'){
                document.getElementById('jokeDisplay').innerHTML = `
                    <p>${data.joke}</p>
                    `;
            }
            if (data.type == 'twopart'){
                document.getElementById('jokeDisplay').innerHTML = `
                    <p>${data.setup}</p>
                    <p>${data.delivery}</p>
                    `;
            }
        })
        .catch(error => {
            throw new Error(data.error_message);
    });
}

Working Demo

And here is our completed example. If you made it this far I hope you learned something. Click on the button and enjoy the jokes.

...I am fetching a joke.

Disclaimer: I am not responsible for the content of these jokes. You can blame the API.