JS APIs Intro

An API is a set of ready-made tools you can use without knowing how they work inside. You have used APIs all along: Math, Date, JSON, and fetch are all APIs. This section is about the ones built into the browser, which let your pages talk to servers, find your location, save data, and run work in the background. This lesson explains what an API is, the two kinds you will meet, and the habits that apply to all of them.

// What an API Is

API stands for Application Programming Interface. Think of a restaurant menu: you do not need to know how the kitchen works. You read what is on offer, ask for it in the right way, and a result comes back. An API is the menu for a piece of software: a list of things you can ask for, and how to ask.

• You see only the interface (the names and what they do), not the inner workings
• You follow the rules: the right name, the right arguments
• You get a result back, or an error if you asked wrongly

// Two Kinds You Will Meet

The two work together. A browser API (fetch) is the tool you use to call a server API (a URL that returns JSON). This section teaches the browser ones in depth.

// A Tour of Browser APIs

// Is It There? Check Before You Use It

Browsers differ in age and settings, so an API you want may be missing. Check first, as you did with navigator in the Navigator lesson:

const checks = {
  fetch: "fetch" in window,
  storage: "localStorage" in window,
  workers: "Worker" in window,
  geolocation: "geolocation" in navigator,
  notifications: "Notification" in window,
  observer: "IntersectionObserver" in window
};
console.log(checks);

// Using an API: The Pattern

Almost every API follows the same steps:

1. Find the documentation. It lists the names, the arguments, and what you get back
2. Check support. Is the feature there? Does it need a secure page (https) or permission?
3. Call it correctly. The right method, the right options
4. Wait if it is asynchronous. Many calls return a promise or take callbacks, because they take time
5. Handle failure. Permission denied, no network, bad input: plan for each

// Calling a Server API

A server API is just a URL with some options in the query string. Build it with the URL object so the encoding is right:

const url = new URL("https://api.example.com/v1/scores");
url.searchParams.set("student", "Ava");
url.searchParams.set("limit", 3);
console.log(url.href);

// Reading the Server's Answer: Status Codes

Every response has a three-digit status code. The first digit tells you the family:

function describe(status) {
  if (status >= 200 && status < 300) return "success";
  if (status === 401 || status === 403) return "not allowed";
  if (status === 404) return "not found";
  if (status === 429) return "slow down";
  if (status >= 500) return "server problem";
  return "other";
}

console.log([200, 201, 404, 429, 503].map(describe));

// Keys, Limits, and Safety

• Many server APIs need an API key, a code that says who is calling. Never put a secret key in front-end JavaScript: anyone can read your page's code. Keep secret keys on a server
• APIs have rate limits: too many requests in a short time get a 429. Cache answers and do not call in a tight loop
• A page can call another site's API only if that site allows it (CORS), as the JSON Fetch lesson explained
• Check an API's terms of use. Some forbid storing the data or require a credit line

// Quick Check

const u = new URL("https://api.example.com/items");
u.searchParams.set("page", 2);
console.log(u.search);

// Try It

▶ Open Playground

1. Click Open Playground and run it. Which APIs are available in your browser?
2. Add one more check for an API you are curious about, such as "share" in navigator
3. Build a URL for a made-up API with three query values, one of which has a space
4. Write the describe function so it also reports "redirect" for status 301