APIs

An introduction to APIs

slides | md

Introduction

Review the following sections and perform the activities on your own or with your group.

Perform the task(s) when you see this ๐Ÿ‘‰ emoji

Learning Objectives

Students who complete the following will be able to:

  • Define essential API terms such as authentication, request, response, client, and server
  • List methods for connecting to APIs
  • Explain why some APIs require authentication
  • Use different clients to access data from the National Weather Service and other APIs
Preparation

Complete the following to prepare for this module

You already use APIs

When you access dynamic code on the internet or use a mobile app, you're using an API.

*While "API" can also refer to a specification, or how a standard is exposed, this presentation discusses web services.

Application Program Interface

An API is a software service that provides data or functionality, usually to other software.

  1. A Client (web page, mobile or desktop app) makes a request
  2. The Server processes the request, queries a database if needed
  3. Server sends response, and client does something with the data

APIs are like search engines

When using an API for data, the process is essentially the same

  1. Using a browser (client), you enter terms and click search in a UI to make a request
  2. The server processes your request, queries their database
  3. And returns a response (HTML of results), which the browser renders as a page.

The key difference between "interfaces" they provide

  • A search engine interface makes data usable for humans in a GUI
  • APIs provide an interface to machine-readable data for programs.

Test an API request

The method you use to send an API request depends on your context. You can easily test:

  • Using a web browser
  • Use an API-testing client like REQBIN or Postman
  • Use wget or curl on a command line

๐Ÿ‘‰ Install the JSON Formatter browser extension to help view the formatted JSON

Test an API in the browser

A web browser can send a request to a public API via it's endpoint (the URL that provides specific data or functionality). The National Weather Service (NWS) API endpoint returns JSON data with our weather: (click to view) ๐Ÿ‘‰ https://api.weather.gov/gridpoints/GSP/116,76/forecast. To understand how that works, we look at the documentation...

{
    ...
    "temperature": 70,
    "temperatureUnit": "F",
    ...
}

Of common software-independent, machine readable data exchange formats, JSON is most popular (over XML) because it is lightweight and easy to use with Javascript.

NWS API - 1 - Get Lat,Lng

Their documentation says to get a forecast, we send a request with our current (decimal) latitude and longitude to the /points endpoint, formatted like:

https://api.weather.gov/points/{latitude},{longitude}

The decimal Lat,Lng for Davidson College is 35.499302,-80.848686

NWS API - 2 - Get Gridpoint

Now we can use this in the request to get our gridpoint ๐Ÿ‘‰ https://api.weather.gov/points/35.499302,-80.848686

The response includes several data points, like our grid office gsp and position 116,76

"forecast": "https://api.weather.gov/gridpoints/GSP/116,76/forecast",
"forecastHourly": "https://api.weather.gov/gridpoints/GSP/116,76/forecast/hourly",

NWS API - 3 - Get Forecast

Using the /gridpoints endpoint we can send a request to get the forecast ๐Ÿ‘‰ https://api.weather.gov/gridpoints/GSP/116,76/forecast

"periods": [{
    "name": "Today",
    "temperature": 78,
    "shortForecast": "Mostly Sunny",
},{
    "name": "Tonight",
    "temperature": 62,
    "shortForecast": "Slight Chance Rain Showers",
}]

The full response includes the time, temperature, conditions, and links to icons:

๐Ÿ”‘ API authentication

  • The first example used free, open data from the U.S. government, but many APIs require authentication, which means you need to create an account and make requests with a special key to verify your identity.
  • API creators use authentication to prevent abuse. If you make too many requests your key may temporarily stop working (the NWS rate limit = 5 seconds).
  • It is essential to read an API's documentation to learn how to use their endpoints, and other requirements.

Why are most APIs free?

Companies build APIs for various reasons:

  1. To allow access to data and software used by employees in a company
  2. To provide data and functions for their public mobile apps
  3. To encourage developers to build 3rd party apps that drive users and engagement
  4. Free access to services makes other companies to increase dependency

Why are most APIs free?

  • The Instagram app is just another type of client.
  • It relies on their API to collect your data and render information and media in an interface.
  • Like many other companies, they give free, but limited access to their users' data to 3rd party developers in order to drive engagement.

Use REQBIN to test APIs

Go to REQBIN

๐Ÿ‘‰ Create a new GET request with this URL and click Send

https://jsonplaceholder.typicode.com/users

You will see Status: 200 OK and a collection of "users" if your request was successful.

*JSON Placeholder is a free fake API for testing

URL anatomy

The parts of this URL https://jsonplaceholder.typicode.com/users

  • HTTPS (Hypertext Transfer Protocol Secure) - enables secure (encrypted) communication over a computer network
  • jsonplaceholder.typicode.com - the API host
  • /users - the endpoint

Request methods are standards for exchanging data between clients and servers:

  • GET - requests data, parameters are included in the URL so can be bookmarked https://www.google.com/search?q=cats
  • POST - sends data in the HTTP message body so has no length restrictions

๐Ÿ‘‰ API Practice

Continue exploring APIs with a browser, REQBIN, or Postman using the following No Auth APIs.

๐Ÿ‘‰ API Practice

API collections to explore. If authentication is required you need to register with them first.

Using code to get API data

  • API creators often publish SDKs (development kits) to simplify requests
  • Most languages have built-in code for asynchronous requests, like Javascript's fetch()

Postman (optional, account required)

Specific APIs

Examples from previous classes...

Digital Public Library of America (DPLA)

"creator": ["Jones, Leslie, 1886-1967"],
"title": ["Kittens"],
"subject": [
    {"name": "Cats"}, {"name": "Baby animals"}
],
"format": [
    "Photographs", "Glass negatives"
],

๐Ÿ‘‰ link to above photo

Wikipedia

  • Retrieve articles and metadata from wikipedia.org
  • docs - free | auth: no / yes (๐Ÿ”‘ for bots)
  • /query = https://en.wikipedia.org/w/api.php?format=json&action=query&titles=cat&prop=revisions&rvprop=content
  • Used by - Wikiscanner (2002-07)
"title": "Cat",
"revisions": [{
    "contentformat": "text/x-wiki",
    "contentmodel": "wikitext",
    "*": "{{Short description|Domesticated felid species}}
        {{About|the species that is commonly kept as a pet|the cat family|Felidae|other
        uses|Cat (disambiguation)|and|Cats (disambiguation)}}"
}]
...

OpenSecrets

  • Retrieve data about money in politics from opensecrets.org
  • docs - free | auth: ๐Ÿ”‘ required | non-commercial only | limit: 200/day
  • /getLegislators = https://www.opensecrets.org/api/?method=getLegislators&id=WV&apikey=API_KEY
  • /candIndByInd ๐Ÿ“„ = https://www.opensecrets.org/api/?method=candIndByInd&output=json&cid=N00032838&cycle=2018&ind=E1210&apikey=API_KEY ๐Ÿคจ
{ "response": {
        "cand_name":"Manchin, Joe", "cid":"N00032838", "cycle":"2018",
        "industry":"Coal mining", "chamber":"S", "party":"D", "state":"West Virginia",
        "total":"40550", "indivs":"29050", "pacs":"11500", "rank":"6" }
}

Spotify

  • Retrieve metadata about music artists, albums, and tracks using Spotify Web API endpoints.
  • docs - free | auth: yes ๐Ÿ”‘ - make an app, then get token with appropriate permissions
  • /me = https://api.spotify.com/v1/me
  • /me/top/artists = https://api.spotify.com/v1/me/top/artists
  1. Login to the developer dashboard and create an app
  2. Test the /me endpoint in their Console. Click Get Token and select all required scopes.
  3. Click Try It to make a request or copy your token and the endpoint you wish to test into Postman.

Keep practicing

Notes/Tips

  • APIs are always changing - Before Facebook (and Instagram) added restrictions to their APIs anyone (artists, researchers, anti-press governments) could download entire databases. Thanks to various cultural works and activism this has changed (see iknowwhereyourcatlives.com, givememydata.com).
  • If you are building an interface or processing the data, save the API result in a local .json file and point to that URL so you don't exceed the API rate limit when testing,

References

More on APIs

Use Postman to test APIs

Postman is an API development client. Once you install the app and login:

๐Ÿ‘‰ Create a new GET request with this URL and click Send

https://jsonplaceholder.typicode.com/users

You will see Status: 200 OK and a collection of "users" if your request was successful.

*JSON Placeholder is a free fake API for testing

Authentication with Postman

To reuse a token across multiple (e.g. Spotify) requests in Postman:

  1. Create a collection named Spotify
  2. In the Spotify collection
    1. In Variables - Add a new variable named token. Paste the token in value (use select all!).
    2. In Authorization - Set Type to OAuth2.0 and then reference the variable with {{token}}
  3. In Authorization for each request, choose "inherit from parent" to use the token

Note: APIs are not always perfect. For example, the /me/top/{type} endpoint is not documented well. You have to enter values for ALL parameters to make it work.

Presentation comments ...

--- ### Contents 1. [Introduction](#introduction), [Required tools](#required-tools) 1. [About APIs](#about-apis) 1. [Make an API request](#make-an-api-request) 1. [Test an API in the browser](#test-an-api-in-the-browser) 1. [National Weather Service API](#national-weather-service-api) 1. [API authentication](#api-authentication) 1. [Why are most APIs free?](#why-are-most-apis-free) 1. [Keep practicing](#keep-practicing), [References](#references) 1. [Use Postman to test APIs](#use-postman-to-test-apis)

APIs come and go...

- [JokeAPI](https://sv443.net/jokeapi/v2/) - Random jokes <a href="https://v2.jokeapi.dev/joke/Any?blacklistFlags=nsfw,religious,political,racist,sexist,explicit" target="_blank">/joke</a>

- [Bored API](https://www.boredapi.com/documentation) - Get a new random <a href="http://www.boredapi.com/api/activity/" target="_blank">/activity</a>

- [faker.hook.io](https://fakerjsdocs.netlify.app/) uses [faker.js](https://github.com/marak/Faker.js/) - [name.findName&locale=de](http://faker.hook.io/?property=name.findName&locale=de), [hacker.phrase](http://faker.hook.io/?property=hacker.phrase), [companyName](http://faker.hook.io/?property=company.companyName) ([see list](http://faker.hook.io/?property=))

- [fakercloud](https://fakercloud.com/api) ๐Ÿ”‘

[`$.ajax()`](https://www.w3schools.com/jquery/jquery_ref_ajax.asp) or

<a href="../assets/img/data-apis/data-apis-dlpa-response-cropped.png"><img width="100%" src="../assets/img/data-apis/data-apis-dlpa-response-cropped.png"></a>

<a href="../assets/img/data-apis/data-apis-wikipedia-cropped.png"><img width="100%" src="../assets/img/data-apis/data-apis-wikipedia-cropped.png"></a>