Using API's

INFO 253A: Frontend Web Architecture

Kay Ashaolu

API

  • Application Programming Interface

What is an API?

From Quora: An API (Application Programming Interface) is best thought of as a contract provided by one piece of computer software to another.

Simple API: a function in JavaScript

function getMaximum(num1, num2) {
	/* ...
	   working code
	   ...
	*/

	return answer;
}

Simple API: a function in JavaScript

  • Imagine that you didn't know how that function was implemented
  • You only know that you enter two numbers in the function and you receive the greater of those two numbers
  • That is an API!

API as contract

  • The getMaximum function can be considered as one piece of computer software
  • The rest of your code can be considered as another piece of computer software
  • The contract between those two pieces of software:
    • If you call the getMaximum function and pass it two numbers as data
    • It will return a number that is the maximum of the numbers provided.

API as a contract example

../js/api.js

function getMaximum(num1, num2) {
	let answer = num1;

	if (num1 < num2) {
		answer = num2;
	}

	return answer;
}

API as a contract example

index.html

<!DOCTYPE html>
<html>
	<body>
		<button onclick="alert(getMaximum(5, 3))">
			Call API function getMaximum
		</button>
		<script src="../js/api.js"></script>
	</body>
</html>

API as a contract example

  • api.js defined an API action called getMaximum
  • It accepts two pieces of information: two numbers
  • It returns one piece of information: a number
  • Any web page can import api.js and by following the above contract can utilize the getMaximum function

Now what really is an API?

  • When people say an API, they don't really mean what we just covered
  • So let's talk about what people really mean when they say "API"

Now what really is an API?

The power of APIs

  • Web applications used to combine all of their functionality in their website
  • Now they separated their "functions" into independent APIs so that clients other than their own websites can use it
  • So now anyone can access that information

The power of APIs Example

  • Without API: An app finds the current weather in London by opening http://www.weather.com/ and reading the web page like a human does, interpreting the content.
  • With API: An app finds the current weather in London by sending a message to the weather.com API (in a structured format like JSON). The weather.com API then replies with a structured response.

APIs over HTTP

  • Let's take that function concept to the Internet
  • We can define functions that can be called "through the Internet" using the HTTP protocol
  • We can use the same protocol as we do for web servers to send and receive information
  • Caveat: Instead of sending HTML/CSS/JS, we send and receive a more structured data representation, like XML or JSON

JSON

  • JavaScript Object Notation
  • A lightweight format that is used for data interchanging
  • It's a subset of the JavaScript language
  • It's the way objects are built in JavaScript

JSON Example

{
	"coord": {
		"weather": [
			{
				"id":800,
				"main":"Clear",
				"description":"clear sky",
				"icon":"01d"
			}
		],
		"base": "stations",
		"main": {
			"temp":294.787,
			"pressure":1024.49,
			"humidity":52,
			"temp_min":294.787,
			"temp_max":294.787,
			"sea_level":1032.69,
			"grnd_level":1024.49
		}, ...

JSON Example

  • The previous example was the response to a call to the OpenWeather API
  • We send a GET request to the OpenWeather API server sending a single parameter:
    • "q" to query for the city
  • We get the JSON response from the previous slide

How to call an API

Let's use curl!

curl -v "http://api.openweathermap.org/data/2.5/weather?\
q=Berkeley,ca"

API HTTP Response

HTTP/1.1 401 Unauthorized
Server: openresty
Date: Fri, 02 Nov 2018 12:34:35 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 107
Connection: keep-alive
X-Cache-Key: /data/2.5/weather?q=berkeley,ca
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST

Connection #0 to host api.openweathermap.org left intact
{"cod":401, "message": "Invalid API key.
	Please see http://openweathermap.org/faq#error401 for more info."}

We got a 401 error

From website: Starting from 9 October 2015 our API requires a valid APPID for access. Note that this does not mean that our API is subscription-only now - please take a minute to register a free account to receive a key.

We got a 401 error

  • Remember that 400s HTTP response codes mean that there is a client error
  • So we made a mistake
  • Now this openweathermap API requires an appid and it's telling you to sign up and generate one

But what is an appid?

  • Many API's require some sort of identification so that the API knows who is making the requests
  • Typically the backend will assign id's by user or by application (one user could have several applications)
  • Statistics, rate limiting, blocking, and levels of authorization are all possible when you require application ids to be passed on every request

How do you typically get an appid?

  • First you will need to go to the website that hosts the application and go through their signup process
  • Next look for somewhere where they tell you how to use their API: typically they will show you how to generate a new application id
  • Let's do this now: Openweathermap signup

Now we have an appid!

  • af578739923ac7f173a6054b24c606ea
  • We can now add our appid in our curl query to get a 200 response back

How to call an API

curl -v "http://api.openweathermap.org/data/2.5/weather?\
q=Berkeley,ca&appid=af578739923ac7f173a6054b24c606ea"

How to call an API Response

Note the Content Type

HTTP/1.1 200 OK
Server: openresty
Date: Thu, 20 Oct 2016 22:54:46 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 461

{
	"coord": {
		"weather": [
			{
				"id":800,
				"main":"Clear",
				"description":"clear sky",
				"icon":"01d"
				...

How to call an API

  • Since this API function call is using a GET request, we can use the address bar on a browser to call this API function
  • For POST requests, we cannot do this

Questions?