Lesson Weekend

Now that we have a decent handle on the basics of User Interfaces in Android applications, let's get more complex! This week we'll begin pulling data from third-party APIs to display in our applications.

We will use the Yelp API to gather restaurants in the zip code provided by the user and display them in the RestaurantsActivity of our MyRestaurants app. This will allow us to return restaurants in any zip code, instead of simply hard-coding a list of several restaurants!

In this lesson we'll begin familiarizing ourselves with the Yelp API, including checking out its documentation and available endpoints. Then we'll walk through obtaining our own Yelp API credentials to authenticate requests. In the next lesson we'll begin programming MyRestaurants to make calls to the Yelp API using these new credentials. Let's get started.

Yelp Fusion API

First things first, take a glance at the Yelp API Documentation before we begin. We're going to use the latest version of the API, also known as Yelp Fusion or Yelp API v3 (note that these are two different names for the same exact API). So, make sure any resources or documentation you reference during this course are specifically meant for v3/Fusion. Previous versions of Yelp's API work differently, so resources meant for v1 and 2 aren't guaranteed to be transferrable.

API Endpoints

As depicted in the documentation linked above, the API contains many different endpoints. For instance, there's an endpoint to retrieve reviews about a business, an endpoint to locate events in specific areas, and even an endpoint to return a business' phone number.

Our MyRestaurants application will specifically use the search endpoint to locate restaurants and their pertinent details in the zip code provided by the user. Take a look at the parameters and response for this endpoint now.

Accessing the Yelp Fusion API

However, like many other APIs, we'll need to send credentials along with our request to successfully retrieve information from this endpoint. As you learned in JavaScript, API keys (sometimes also called "tokens" or "credentials") give us permission to request data. Among other things, this helps API owners ensure people and applications aren't bogging down their API with an unnecessarily large number of requests. Let's walk through how to obtain our own unique credentials.

Previous APIs we've used, like OpenWeather, and BetterDoctor require we make an account on their website. Yelp does too, but we need to complete a few extra steps too. Let's walk through these now:

1. Create Yelp Account

First things first, we'll need a Yelp account. This is the same as the standard account all their users have. So, if you've used Yelp previously, you can use your existing account. Otherwise, you'll need to sign up here.

2. Create New API App

Next, we'll need to login to our new or existing account and visit the Create New App area of the Developer's section of Yelp. You'll be prompted to fill out a form with multiple fields.

  • For App Name list MyRestaurants.
  • Don't worry about including an App Website.
  • Under Industry, select either Food & Drink or Education.
  • You can list Epicodus as the Company.
  • In Description feel free to write a brief sentence about your application and/or about how this is a school project.

After submitting the form we should be taken to a page with a green success message, and details about our new API Credentials. You should have a Client ID and a Client Secret (you'll have to click the Show link to display it). You should also notice an API rate limit of 25,000 requests per day. Awesome! Keep this information handy, we'll need it in just a moment.

3. Send POST Request to Receive Access Token

So far this pretty similar to how we signed up for other API keys. However, it's about to get a little different. You see, the Client ID and Secret we just received aren't actually the credentials we'll code into our application! Instead, the Yelp Fusion API requires we use these two pieces of data to send a POST request to a special endpoint to receive an access token. This access token is what we'll code into our application. As described in the Authentication section of the Yelp Fusion API Documentation this is known as OAuth2 authentication protocol.

This may sound a little complex, but here's the deal: We don't need to do this every single time we make an API request. So we don't need to program our application to make this POST request. Instead, we can simply construct and send a POST request manually in Postman to receive our access token. Then we can code this token directly into our project. Let's do this now.

(Note: If you'd like a refresher on using and/or installing Postman, revisit the Testing API Calls with Postman lesson from JavaScript now.)

  • Open Postman, navigate to the Builder tab.
  • Select POST in the left-hand dropdown menu.
  • To the right of the dropdown is a field reading Enter request URL. Place the URL https://api.yelp.com/oauth2/token here. This is the API endpoint we'll make a POST request to.
  • Under the URL field select the Body tab. This will open up a form where we can construct the body of our request.
  • The top of the Body section offers several radio button options. Select x-www-form-urlencoded.
  • Below this enter the required parameters as key-value pairs:
    • Under the first Key enter grant_type. In Value enter client_credentials.
    • Under that, we'll add another key-value pair: In Key enter client_id. Then, in Value insert the unique client ID provided to you by Yelp.
    • In a third line, enter a Key of client_secret and insert the unique client secret value provided to you by Yelp.

After completing these steps our Postman screen should look as follows. Double-check yours against this example now:

Once everything is in place, hit the blue Send button to execute the POST request.

4. Retrieve Access Token from API Response

After sending the request we should see a response appear in Postman. It should look something like this:

As you can see, this contains our access_token. Keep this information available. We'll integrate it into our application in the next lesson. Additionally, tokens don't expire until Jan 18, 2038. (Seriously, check it out.) So, once we've successfully created our token, we shouldn't have to make a new one for a loooong time, unless you delete the App you created on Yelp's website to receive your Client ID and Secret.

In the next lesson we'll discuss how to integrate our new token into our app.

Overview


Accessing the Yelp Fusion API

1. Create Yelp Account

If you've used Yelp previously, you can use your existing account. Otherwise, you'll need to sign up here.

2. Create New API App

Login the account and visit the Create New App area. You'll be prompted to fill out a form with multiple fields.

  • For App Name list MyRestaurants.
  • Don't worry about including an App Website.
  • Under Industry, select either Food & Drink or Education.
  • You can list Epicodus as the Company.
  • In Description feel free to write a brief sentence about your application and/or about how this is a school project.

After submitting the form you should have a Client ID and a Client Secret.

3. Send POST Request to Receive Access Token

The Yelp Fusion API requires we use these two pieces of data to send a POST request to a special endpoint to receive an access token. This access token is what we'll code into our application.

  • Open Postman, navigate to the Builder tab.
  • Select POST.
  • In Enter request URL paste the URL https://api.yelp.com/oauth2/token
  • Navigate to the Body tab.
  • The top of the Body section offers several radio button options. Select x-www-form-urlencoded.
  • Below this enter the following three required parameters as key-value pairs:
    • Key: grant_type. Value: client_credentials.
    • Key : client_id. Value : the client ID provided to you by Yelp.
    • Key : client_secret. Value: the client secret provided to you by Yelp.
  • Hit the blue Send button to execute the POST request.

4. Retrieve Access Token from API Response

After sending the request we should see a response appear in Postman that contains an access_token. Keep this information available. We'll integrate it into our application in the next lesson.