Intro to APIs:

What are they? Why and how use them?

Brian Norberg

IT Analyst, Trinity Technology Services

brian.norberg@duke.edu

In this workshop, you will learn:

  • What is a web API
  • What is required to make a REST API call
  • Why and how we use APIs
  • Practice with APIs through the use of GUIs (graphical user interfaces)
  • Call APIs through prewritten software
  • Write a little API code

 

In this workshop, you will need:

 

What is an API

API = set of commands to access information provided by the company who “owns” that information. It is the "hidden" portion of a website that is meant for computer consumption not user viewing.

Client

 

Server

 

  • Every time you register for a new app using your Facebook, Google, or Twitter account
  • Whenever you see a map on a restaurant’s website showing you where you can find it
  • Using Microsoft Azure Face API to auto crop uploaded pictures to focus on people within them

Examples of APIs in Action

  • Make life easier for developers by exposing code that allows substantial shortcuts (e.g., Google Maps, Leaflet)
  • Increase the use of a platform (e.g., Twitter and Facebook)
  • Provide a service. A good example of this is all the API code out there for computation (e.g., IBM Watson, Google Vision)

Why Companies build APIs

API in action

Go to my hometown, Chicago, in OpenStreetMaps, https://www.openstreetmap.org/relation/122604

 

Open a new browser tab and go to the OpenStreetMap api to request information about Chicago, https://www.openstreetmap.org/api/0.6/relation/122604

 

Now let's look at the API docs to see what is happening above:

https://wiki.openstreetmap.org/wiki/API_v0.6#Elements_2  

Parts of a REST API

A web API is simply another program running on a web server. It may be part of the same program that handles web traffic or it can be completely separate.

1) root url - the url to access the API (if you see the word "api" as subdomain or subfolder - eg, api.twitter.com - that means the API is a separate program on the server

2) endpoints - a unique url to a given resource or collection of resources ( eg, googlemaps.com/api/cities)

3) request methods - get, post, put, delete

4) parameters - directives you can add to the url to filter the returned results (parameters typically follow a "?" in the url string)

WTF... Access Key 

An access key is a person's special ID so the service can distinguish the user and determine access rights

An access key tells the service (the provider of the API) who this person is and that s/he has access to the API and can perform certain (default) functions

REST API in Action

 

Go to the Colab api, https://streamer.oit.duke.edu/dev_console, and login with your netid and password

 

Click the "New API Key" button and fill out the form. Then enable all services.

 

Copy the API Key and click on the "Documentation" button to the left. Paste the key into the text entry box and click the "Explore" button. 

 

WTF...Access Token

Using APIs to make POST requests typically requires special permission and something called an access token 

 

The token tells the service what functions a user can perform with that access token

Enter Twitter...

Most APIs require users to register and tell what access you want. The service returns an Access Key and Token after registration.

 

Let's register an app with Twitter so we can test out posting a message to the platform from its API, https://apps.twitter.com.

Configure your Twitter App

Download Postman app

API Call to Twitter with Postman

1) Select "POST" from dropdown list

2) Add "https://api.twitter.com/1.1/statuses/update.json" as POST URL

3) Select "OAuth 1.0" from the "TYPE" dropdown menu, then add your Twitter credentials

4) Select "Request Headers" from the "add authorization data to" dropdown menu

Twitter Post with Postman

1) Click the 'Body' tab

2) Add "status" in the 'key' field

3) Add your message in the 'value' field and hit "Send"

Review Time: How and why we use APIs

How

1) Get access key and token

2) Choose request method (GET, POST, etc.)

3) Read API documentation to learn about endpoints, allowed parameters, and return formats of API

Why

1) To consume data (Get)

2) To create data (POST)

3) To incorporate external code into a web page or app

This is where we are now!

When in Doubt, Google It!

1) Copy into your favorite text editor and save and map.html:

https://gist.github.com/bnorberg/1459c88e0ae4a924bd986f63b0dd4114 

2) Grab your Google Maps API key and enable the "Google Maps Javascript API" by selecting the key and going through the "ENABLE APIS AND SERVICES" link in the top, middle of the console.

3) Find coordinates for the "Oit-Telecommunications Bldg" and "Duke University" and add your API Key

When in Doubt,Use Someone Else's Code

1) Get a OIT VM following these directions, https://duke.box.com/s/y7u16x289ujfrdsimk9mm8llokxyjt40​

2) Install Twarc Twitter archiving tool following these directions, https://duke.box.com/s/14ekzpjb6st0pn7y5cvv8cf1gpank5v9

 

More Practice: Facebook Graph API

Go to the Facebook Graph API, https://developers.facebook.com/tools/explorer, and login with your Facebook credentials (if you are not already logged into Facebook).

 

Change "me" to "DukeUniv" and start messing around with adding parameters to see how the GET URL changes. Use the API documentation to help you, https://developers.facebook.com/docs/graph-api/using-graph-api.

Call Facebook API with other's code

1) Login back into your VM

 

2) Install Fbarc Facebook archiving tool following these directions, https://duke.box.com/s/5i4iq6pdov35zzvgo6ujp6e4dhj0i6wg

Before you leave...help Brian get home

I bike to work and need to steer clear of places I could crash. Help!

1) Download this geojson file of bike crashes in Durham. 

2) Follow the documentation about adding a data layer to a Google map and place the above geojson file on your map.

3) Remove those labels to make it easier for me to see the crashes.

4) Open the map in Firefox. (The other browsers won't like the geojson file being served by your machine instead of a web server.)

Here is the gist for the final map if you need help. Don't forget to add your Google API key.

What's Next?

Explore all the APIs out there: http://www.programmableweb.com/apis/directory

 

Check out Code Academy's  API tutorials: https://www.codecademy.com/apis

 

Learn to Google it: Once you know what API you want to interact with, choose your programming language and Google if there is already a client written in that language to interact with your API of choice. Chances are, there is.

Intro to APIs Old2

By Brian Norberg

Intro to APIs Old2

Slides for Roots Intro to APIs workshop

  • 627