fbpx

Using Third-party APIs

Using Third-party APIs

Objective: By the end of this checkpoint, you will be able to understand Third-party API documentations and be able to use them for development

APIs can be tricky! APIs range from a single function providing a simple result to many thousands of functions providing a variety of results. Some accept parameters and some don’t. Some parameters have constraints on their values and some don’t. Some APIs require special authentication. Some have restrictions on the number of times they may be called. Unfortunately, there is no standard way that any of this is done. So for each API that you wish to use, you need to delve into the documentation and figure out its particular structure and rules.

Key terms

  • Third-party APIs
  • request-response
  • Parameter
  • Query string
  • Endpoint

What are third party APIs?

Simply put, Third party APIs are APIs provided by third parties — generally companies such as Facebook, Twitter, or Google — to allow you to access their functionality via JavaScript and use it on your site. One of the most obvious examples is using mapping APIs to display custom maps on your pages.

As you can see why working with Third-party APIs can be useful, now it’s time to learn how to use them! We will be covering how to work with APIs, how to read API docs, and how to actually use the data coming back from an API.

We’ve brought a friend along to make the journey much easier.

Meet Slash

Slash the API Dog

Slash is Michelle’s adorable, lovable dog. Michelle is a software engineer who builds APIs. Michelle really enjoys her job and has taken inspiration from her work building APIs in training Slash.

As you may know, an API is a collection of commands a user can give to a web service along with a set of responses that match the request. Michelle has trained Slash to do just the same.

Slash is a good boy, knows a variety of commands, and always responds correctly as long as you give him a request he’s been taught. When he gets extra excited, his tail goes crazy — this isn’t something Michelle taught him related to APIs, it’s just because he’s a lovable pup and really enjoys his training!

Step by Step Guide

1. Decide what API you need

What information are you looking for or do you want to change?

Are you trying to grab all of @dougthepug’s Instagram posts? Maybe you want to automatically tweet at anyone who follows your dog’s twitter (because even though dogs can’t speak, they have a lot to say, we know Slash sure does).

If you already know the site or API you’re trying to connect to, go directly to Step 2.

If you’re trying to find data, but aren’t sure where to start, Google is your friend. Search for “[stuff you’re interested in] API” and see what comes up. You might be surprised how much information is out there.

If you’d like a simple example API, you can use the one Michelle made while training Slash. It has some of his favorite commands like retrieving balls and digging holes. We’ll be using it throughout the rest of our examples.

2. Find the API docs

APIs provided by well-known companies should have thorough documentation on how to use them.

To find these, google “[Insert Company] API documentation” or “[Insert Company] developer”.

The results should take you to the developer portal. Look for a link that says “Docs”, “Documentation”, “Reference” or “Technical Reference”.

If the site provides both Documentation and Reference, the Reference section is what you’re looking for, as it will provide specific details about the API and its endpoints. You might want to keep the Documentation section nearby, as it may have guides and other details about the service you’re using.

Within the docs, you may need to look for the specific API you want as sometimes there can be many options. Facebook, for example, has separate APIs for marketing, ads, pages, and more.

If the API you want to connect to isn’t well known (like Slash’s) you may need to ask the developer for documentation. They may have a PDF containing the information you need or online documentation that is not listed on their website.

If you missed the link above, Slash’s API docs can be found here.

3. Find the endpoint

API docs may look daunting, but once you know what to look for they’re usually well structured and pretty standardized.

The first thing to look for is the appropriate endpoint(s). There should be one endpoint corresponding to each type of data you want. An endpoint could look like this: https://slashtheapidog.com/api/bones/{id} or just /bones.

The documentation should have a list of endpoints. They may be top level in the docs or under a section called “reference”, “endpoints”, or “methods”.

To find the right endpoint, look for the name that corresponds with the data you’re looking for. For example, if you want a list of all the holes Slash has dug, /holes is probably the right one. In any case, each endpoint should have a description to help explain what it does.

Slash the API Dog

From his docs, these are the endpoints in Slash’s API related to holes:
GET https://slashtheapidog.com/api/holes
GET https://slashtheapidog.com/api/holes/{id}
POST https://slashtheapidog.com/api/holes
PUT https://slashtheapidog.com/api/holes/{id}
DELETE https://slashtheapidog.com/api/holes/{id}

4. Determine your request type

Now that you’ve found the right endpoint, you need to determine the type of request to send it.

As you know, there are 4 different types of requests:

GET
GET request is how you ask the API to respond with something that it has, most often data. You can ask for specific information about one item or a group of items based on the endpoint and parameters. This is the equivalent of asking Slash to bring you one of his bones or all of his bones.

POST
POST request is how you tell the API to create something new. This is similar to asking Slash to dig (create) a new hole for you.

PUT
PUT request is how you tell the API to update something that was previously created. This is similar to asking Slash to dig deeper (update) into the hole he dug.

DELETE
DELETE request is how you tell the API to delete something that was previously created. This is similar to asking Slash to cover up (delete) a hole he previously dug.

Slash the API Dog

Think about these four types. Are you getting information, creating a new entry, changing an existing entry, or deleting one? That answer tells you exactly what request type you need.

5. Understand the parameters

Many requests require additional parameters. Parameters are the details of your request. For example, if you want Slash to bring you all the balls that are red, you need to specify the color. If you want him to create a new hole, you need to tell him where to put it and how deep to dig.

The API documentation you are referencing should have a section called “Parameters” or “Options” for each endpoint and request type. Pay attention to which parameters are required as some are optional. If a parameter is marked as optional, the docs may provide an example that is also the default.

Slash’s API parameters might look something like this for retrieving balls:

GET https://slashtheapidog.com/api/balls

Name Required Description Example
color required Color of the ball blue
squeaks required Whether the ball is a squeaky toy or not true
size optional Size of the ball in centimeters, measured by diameter 5
material optional Type of material used to make the ball rubber

6. Check for authentication

Most APIs require you to prove you have access to the API through some type of authentication. Slash wouldn’t bring his bone collection to a stranger now would he?!

API documentation will typically have an entire section dedicated to authentication. It may be under a top-level link named “Authentication” or “OAuth” or could be hidden within sections like “Getting Started”, “Guides”, etc.

Look out for the following words when trying to find the authentication documentation: “Authentication”, “Authorization”, “OAuth”, “Token”, “Access”, “Permissions”.

There are many different kinds of authentication. Here’s a brief overview of the most common types:

Basic Auth – Providing a username and password.API Key – Providing a unique key (like a complex password) given to you by the developer of the API.OAuth – A framework for allowing a third-party app to access another API on your behalf. When a separate company asks you to sign in with Google or Facebook credentials in a pop up window, this is usually OAuth.
If you’re looking to access your own information, most likely you will use Basic or API Key authentication. If you are building an app that needs to access other people’s data, you may need to set up OAuth, which is a bit more complicated than what we will cover here.

Assuming you’re not setting up OAuth, you should determine whether you need basic authentication, an API key, or are accessing something that does not require authentication at all. Once you know the type of authentication, you can gather the information you need: username and password for basic or your API secret token, access token, or bearer token for API keys. Typically this information will be sent to the API in the headers, which is another way to send information in a request.

7. Format your request

We’ve got all the information we need! Now we just need to make the request and cross our fingers… But don’t worry, with Slash’s help you’ll surely be headed for success.

Here are three different ways to connect to an API:

cURL – if you know how (and want) to code

cURL is a command line program that allows you to exchange data with APIs via the terminal on your Mac or Windows command prompt.

1. Mac users: Open the terminal (under Applications / Utilities). Windows users: Run the command prompt with admin rights or download curl if you are on an older version of Windows.

2. Try making a GET request with basic authentication by typing “curl -u <username>:<password> <url>”, replacing anything in <> with the actual value. For example, Slash might access his list of bones like this:

curl -u slash:slashpwd https://slashtheapidog.com/api/bones

You should see the response from the API appear on the command line after you hit enter.

3. Try out some other types of requests:

GET request with API key authentication and parameters:
curl -H "Bearer: <key>" <url>?<param1>=<val1>&<param2>=<val2>
curl -H "Bearer: 125309h0ewgah" https://slashtheapidog.com/api/bones?age=2

POST / PUT request with parameters:
curl --data "<param1>=<val1>&<param2>=<val2>" <url>
curl --data "color=red&squeaks=true" https://slashtheapidog.com/api/balls

You can learn more about cURL by reading the full documentation.

8. Understand your response

Now that you’ve made a request we can take a look at the response, it probably looks something like this:

or this:

Most APIs will return JSON like the top example, but some may return XML. Parabola will return the data in a familiar table format.

Hopefully the response you received looks a lot like the above in the sense that you got data back! You can read that data by looking at each key and its value.

Some things to look out for in your response:

Pagination information

Slash may only have dug enough holes to return one page of API results, but yours may have many more.

Parabola and Postman have pagination support, but if you need to learn more about it for your specific use case look for the words “page”, “cursor”, “offset”, or “limit”. Those are all related to pagination and the API documentation should have some information on how to use them to get to the next page.

Errors

You may have received something that doesn’t look like the data you were expecting and resembles an error message.

This means that something went wrong with your request. Most errors will give you some information about what happened so you can make changes to the request. Errors will also be accompanied by a status code in the 400 to 599 range. Learn more about status codes and what they mean here.

9. Use the data

Congrats on making a successful request and receiving a response. Slash is so proud of you!

Slash the API Dog

Now that you have some data (GET) or have been able to make the API take an action (POSTPUT, or DELETE) you will likely want to do something with the data or power. The true power of APIs comes from the way that you work with them.

Being able to ask Slash to fetch a bone for us once is great and we certainly want to play with him. But imagine Slash has hundreds of bones and our goal is to safely bury and log all of his bones. To do that efficiently, we’d need to chain actions together.

We would ask him to GET a bone to us, POST a new hole the same size as his bone, PUT the bone into the hole, GET the coordinates of that hole, and finally POST those coordinates to a tracking doc somewhere so we can have our list of tracked bones in their holes.

What we’ve done here is chained a set of actions together to create a flow. This is just one example, but hopefully you can start to understand the impact of being able to programmatically work with APIs to build more complex flows of actions and data.

 

Looking for some Cool Ideas for your first Capstone Project?

Check these links out and feel free to explore ideas on Web/Youtube

https://dev.to/camerenisonfire/10-intriguing-public-rest-apis-for-your-next-project-2gbd

https://apilist.fun/

https://developers.google.com/youtube/v3/getting-started

https://flaviocopes.com/sample-app-ideas/

https://cloud.ibm.com/developer/watson/documentation

 

Even More Resources on APIs