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
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