Intro to APIs:

What are they? Why and how use them?

slides at https://goo.gl/qHQ2Tq

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 a GUI (graphical user interface)
  • Write a little API code

 

In this workshop, you will need:

 

What is an API

API = set of commands to access a database of information. It is the "hidden" portion of a website that is meant for computer consumption not user interaction. Usually runs on separate "location" from public-facing website.

web API = application running on a web server following the http protocol to interact with data not through a website interface.

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

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

Why 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

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)

 

Try out OpenStreet Maps Search tool Nominatim using Postman.

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, whether access to the API is allowed, and what functions can be performed

1) Go to https://developer.mapquest.com and hit the "get your Free API Key" button and register.

2) Go to Mapquest's Open Search API

3) Open the Postman app so we can create some API calls

4) Try the same with Mapquest's Place Search API

Not All APIs are Created Equal

Use this file to create html page to print your api call results

When in Doubt, Use Other's Code

1) Download the html template from here.   

2) Create a Mapbox account and copy the "default public access token".

3) Fill out the template above following the Leaflet tutorial at https://leafletjs.com/examples/quick-start/​

Finished file here. Add your Mapbox token

Review Time: How and why we use APIs

How

1) Get access key

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, update, or delete data (POST, PUT, DELETE)

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

This is where we are now!

Posting to an API with your Code

1) Get and setup an OIT VM following these directions

2) Get 7-day free trial to Microsoft Azure's Face API service

3) Make test API call with Postman (try this picture and don't forget it's a POST call)

4) Follow this Python tutorial to write your code using the Face API to highlight faces in an image (NOTE: Use directions in above downloaded file to add and run the code.)

5) Try to add code to crop file on faces.

Here is the gist for the final code if you need help. Don't forget to add your Face API key and use the correct regional base url.

Before you leave...get Brian home safely

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

1) Download geojson file of Durham bike crashes and bike crash icon file.

 

2) Follow the documentation about adding a geojson file to a Leaflet map and add the bike crashes. (HINT: Leaflet does not load geojson from a file, so you will have to look to jQuery .getJSON function for help.)

 

3) 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 MapBox Token key.

What's Next?

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.

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

 

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

More API Practice

 

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. 

 

Intro to APIs

By Brian Norberg

Made with Slides.com

Intro to APIs

Slides for Roots Intro to APIs workshop

  • 1,420

More from Brian Norberg