Data from an API

The supplier's API

Bakehouse supplies the bakery's prices. Its API (a small Python server, made up for this lesson and in the practice folder) has one real endpoint and a control panel for the experiments:

• GET /v1/bakes returns today's bakes and prices, if the request carries the right key: Authorization: Bearer test-key-not-secret.
• POST /_control changes its behaviour: {"mode": "down"} answers 503; "slow" waits four seconds; "bad" sends dark rye's price as text, "9.00", instead of a number; {"price": {"dark-rye": 9.5}} changes a price.
• It logs every request, so you can count how often the bakery asks.

(Your machine)

python3 bakehouse_api.py
curl -s http://127.0.0.1:4000/v1/bakes
curl -s -H "Authorization: Bearer test-key-not-secret" http://127.0.0.1:4000/v1/bakes

The first starts the API (leave it running and use another terminal); the other two ask for the bakes without and with the key.

{"error": "missing or wrong API key"}
{"bakes": [{"slug": "country-sourdough", "name": "Country sourdough", "price": 8.5}, {"slug": "dark-rye", "name": "Dark rye", "price": 9.0}, {"slug": "cardamom-bun", "name": "Cardamom bun", "price": 4.25}]}

The API's log:

    1.0s  GET /v1/bakes -> 401 (no or wrong key)
    1.0s  GET /v1/bakes -> 200 (ok; dark rye 9.0)

One module that talks to the API

Every request to Bakehouse goes through one file, lib/bakehouse.js:

import "server-only";

const BASE = process.env.BAKEHOUSE_URL;
const KEY = process.env.BAKEHOUSE_API_KEY;

// Today's bakes from the supplier's API. Runs only on the server.
export async function getBakes(fetchOptions = {}) {
  const res = await fetch(`${BASE}/v1/bakes`, {
    headers: { Authorization: `Bearer ${KEY}` },
    signal: AbortSignal.timeout(2000),          // give up after 2 seconds
    ...fetchOptions,
  });
  if (!res.ok) throw new Error(`Bakehouse answered ${res.status}`);
  return checkBakes(await res.json());
}

// Trust nothing: keep only items with the shape the page needs.
function checkBakes(body) {
  if (!Array.isArray(body?.bakes)) throw new Error("Bakehouse sent no list of bakes");
  const good = body.bakes.filter((b) =>
    typeof b?.slug === "string" && typeof b?.name === "string" &&
    typeof b?.price === "number" && Number.isFinite(b.price));
  if (good.length < body.bakes.length) {
    console.warn(`Bakehouse: dropped ${body.bakes.length - good.length} malformed item(s)`);
  }
  return good;
}

• import "server-only" marks this file as server code. If any client component imports it, even indirectly, the build fails (tested below).
• process.env.BAKEHOUSE_URL and BAKEHOUSE_API_KEY come from environment variables, not the code. Locally they're in .env.local, which Next.js loads automatically and which belongs in .gitignore. In production, they're set in the hosting platform (Lesson 8).
• AbortSignal.timeout(2000) is Lesson 3's AbortController timeout in one line.
• if (!res.ok) throw is Lesson 3's lesson again: fetch doesn't fail on a 503.
• checkBakes keeps only items with a text slug and name and a real number for a price, and logs how many it dropped. The page never sees anything it can't display.
• fetchOptions lets each page choose how this request is cached, which is the rest of this lesson.

.env.local:

BAKEHOUSE_URL=http://127.0.0.1:4000
BAKEHOUSE_API_KEY=test-key-not-secret

The menu page calls it:

import MenuList from "../components/MenuList";
import { getBakes } from "../../lib/bakehouse";

export const metadata = { title: "Today's bakes" };

export default async function MenuPage() {
  const bakes = await getBakes(/* caching choice goes here */);
  return (
    <>
      <h1>Today's bakes</h1>
      <MenuList items={bakes} />
      <p className="note">Prices from Bakehouse at {new Date().toISOString().slice(11, 19)} UTC</p>
    </>
  );
}

The note at the bottom records when the page was made, which shows whether a page is new or a saved copy. And if anything on the page throws, app/menu/error.js is shown instead:

"use client";

// Shown instead of the menu if anything on the page throws.
export default function MenuError({ reset }) {
  return (
    <>
      <h1>Today's bakes</h1>
      <p role="status">We couldn't load today's menu just now. The bakery is open as usual.</p>
      <button type="button" onClick={() => reset()}>Try again</button>
    </>
  );
}

error.js is an error boundary: Next.js puts it around the page in that folder, and shows it if the page fails. It must be a client component, because reset (try again) runs in the browser.

When to ask the API

The same getBakes call can be made at three moments. The page was built four ways, changing only the options passed to getBakes, and the route table recorded what each became:

The interval build's table gained two columns, Revalidate and Expire:

Route (app)                    Revalidate  Expire
├ ○ /menu                             10s      1y

The first surprise is the first row. Next.js's documentation says fetch isn't cached by default, and that's true of the response. But the page that uses it was still built as static: with nothing in it that depends on a particular visitor, Next.js fetched once during the build and saved the finished page.

Freshness, measured

To see what each means, a script builds the page one way, starts it, changes dark rye's price at the supplier, and reloads the page over the next 16 seconds, counting the supplier's log lines:

api '{"price": {"dark-rye": 9.5}}'
for t in 1 6 11 12 16; do
  # wait until t seconds have passed, then:
  echo "   ${t}s  page says dark rye $(ask)"
done

api posts to Bakehouse's control panel; ask fetches /menu with curl and pulls out dark rye's price. The full script is in the practice folder. The results:

== static (no cache option), clean build: getBakes()
   0s   page says dark rye $9.00
        (supplier changes dark rye to $9.50)
   1s  page says dark rye $9.00
   6s  page says dark rye $9.00
   11s  page says dark rye $9.00
   12s  page says dark rye $9.00
   16s  page says dark rye $9.00
   supplier API calls after startup: 0

== no-store: getBakes({ cache: "no-store" })
   0s   page says dark rye $9.00
        (supplier changes dark rye to $9.50)
   1s  page says dark rye $9.50
   6s  page says dark rye $9.50
   11s  page says dark rye $9.50
   12s  page says dark rye $9.50
   16s  page says dark rye $9.50
   supplier API calls after startup: 6

== revalidate every 10 s: getBakes({ next: { revalidate: 10 } })
   0s   page says dark rye $9.00
        (supplier changes dark rye to $9.50)
   1s  page says dark rye $9.00
   6s  page says dark rye $9.00
   11s  page says dark rye $9.00
   12s  page says dark rye $9.50
   16s  page says dark rye $9.50
   supplier API calls after startup: 1

• Static never changed. The page was made during the build, and the supplier wasn't asked once after the server started. The price stays $9.00 until the next build.
• Every request was current within a second, and asked the supplier six times for six page loads. A thousand visitors an hour is a thousand calls an hour, and the page is only ever as fast as the supplier.
• Every 10 seconds showed the old price until 11 seconds, then the new one, with one call. Here's how: when a request arrives after the interval has passed, Next.js serves the saved page anyway and rebuilds it in the background. The 11-second request got the old page and triggered the rebuild; the 12-second request got the new one. That's called stale-while-revalidate, and it means one visitor per interval sees a slightly old page, so that nobody waits for the supplier.

Enlarge (opens the diagram full size)

Close

A rebuild that didn't refresh

While running these tests, the static page once showed $9.50 straight after a build, though the supplier had just been reset to $9.00, and the supplier's log showed no request during that build. Next.js had reused a response saved in its build cache, .next/cache/fetch-cache, by an earlier build. So the test was repeated on purpose: build cleanly, change the supplier's price to $9.75, and build again with the cache still there:

== rebuild with the build cache still there
   supplier says dark rye $9.75; API calls during the build: 0
   page says dark rye $9.00
== rebuild after deleting .next/cache/fetch-cache
   API calls during the build: 1
   page says dark rye $9.75

The rebuild made no API calls and kept the old price. Deleting the cache folder fixed it. The documentation says a default fetch runs once during next build; in this test, with a warm cache, it ran zero times. CI systems are often set up to keep .next/cache between builds, because it makes builds faster. If a site redeploys to pick up new data, that's exactly when this bites. Two safe habits: give data that changes a revalidate interval (or no-store), so freshness doesn't depend on builds at all; and when a build must pick up new data, clear the fetch cache first.

When the API misbehaves

Each failure was tried against the every-request page, then the interval page. A script switches Bakehouse's mode and reads the page's main content and HTTP status.

Every request

== per request (no-store)
-- supplier: ok
   HTTP 200, 0.075909s: Today's bakes Country sourdough $8.50 Dark rye $9.00 Cardamom bun $4.25 Prices from Bakehouse at 03:59:49 UTC
-- supplier: down
   HTTP 500, 0.031082s: 
   JavaScript on : HTTP 500, main says: "Today's bakesWe couldn't load today's menu just now. The bakery is open as usual.Try again"
   JavaScript off: HTTP 500, main says: ""
-- supplier: slow
   HTTP 500, 2.020825s: 
-- supplier: bad
   HTTP 200, 0.015484s: Today's bakes Country sourdough $8.50 Cardamom bun $4.25 Prices from Bakehouse at 04:00:25 UTC
-- server log lines from the app
   ⨯ Error: Bakehouse answered 503
   ⨯ Error: Bakehouse answered 503
   ⨯ Error: Bakehouse answered 503
   ⨯ Error [TimeoutError]: The operation was aborted due to timeout
   Bakehouse: dropped 1 malformed item(s)

• Down: the page returned HTTP 500, and curl's copy had an empty main area. In a browser with JavaScript, the error boundary appeared: "We couldn't load today's menu just now", with Try again. With JavaScript off, the page was blank. Because error.js is a client component, its message only appears once JavaScript runs: Lesson 3's progressive enhancement problem, in a new place.
• Slow: the timeout fired at 2.02 seconds, and the page failed the same way. Without it, every visitor would have waited four seconds, and on a truly stuck API, until something else gave up.
• Bad data: dark rye's text price was dropped, the rest of the menu showed, and the server logged "dropped 1 malformed item(s)". Without checkBakes, MenuList's b.price.toFixed(2) would have thrown on a string, and the whole menu would have been the error page.
• The log has a line for each failure. On a real site, those lines are how you find out before customers tell you.

Every 10 seconds

== refresh every 10 s, supplier goes down
-- supplier: ok
   HTTP 200, 0.009538s: Today's bakes Country sourdough $8.50 Dark rye $9.00 Cardamom bun $4.25 Prices from Bakehouse at 04:00:32 UTC
-- supplier: down, 11 s later
   HTTP 200, 0.005922s: Today's bakes Country sourdough $8.50 Dark rye $9.00 Cardamom bun $4.25 Prices from Bakehouse at 04:00:32 UTC
   HTTP 200, 0.004426s: Today's bakes Country sourdough $8.50 Dark rye $9.00 Cardamom bun $4.25 Prices from Bakehouse at 04:00:32 UTC
-- server log lines from the app
   ⨯ Error: Bakehouse answered 503
   ⨯ Error: Bakehouse answered 503
   Error: Bakehouse answered 503

Visitors never noticed. When the background rebuild failed, Next.js kept serving the last good page: same menu, same "04:00:32" timestamp, HTTP 200, in about 5 milliseconds. The failures went to the log instead of to customers. For a menu, a price that's a few minutes old is far better than an error page, which makes an interval the right choice for most pages built on someone else's API.

Keeping the key secret

A quick check that the key never reached the browser:

== is the key in any browser JavaScript?
   files in .next/static containing it: 0

Then the mistake server-only exists to catch: a new client component, PriceCheck, imports getBakes to check prices from a button. The build:

> Build error occurred
Error: Turbopack build failed with 2 errors:
./lib/bakehouse.js:1:1
Error: You're importing a module that depends on "server-only". This API is only available in Server Components in the App Router, but you are using it in the Pages Router.
    Learn more: https://nextjs.org/docs/app/building-your-application/rendering/server-components
> 1 | import "server-only";
    | ^^^^^^^^^^^^^^^^^^^^^
  2 |
  3 | const BASE = process.env.BAKEHOUSE_URL;
  4 | const KEY = process.env.BAKEHOUSE_API_KEY;
Ecmascript file had an error

The build refused, which is the point: code that holds a key can't end up in the browser by accident. One oddity: the message says "you are using it in the Pages Router", though this app only uses the App Router. Error messages aren't always right about why; the import trace that followed it (PriceCheck.js, a client component, importing lib/bakehouse.js) shows exactly where the problem is.

Two rules about environment variables in Next.js:

• Variables are server-only by default. process.env.BAKEHOUSE_API_KEY in client code would just be undefined. Without server-only, that mistake doesn't fail the build; it fails quietly in the browser.
• NEXT_PUBLIC_ variables are copied into browser JavaScript at build time. Name a variable that way only if you'd be happy to publish its value. Never put a key in one.

Spot the problem

Work out what's wrong before you read the explanation.

"We redeploy every morning to update prices." A shop's product pages fetch prices from its stock system with no cache options. Prices change overnight, so a scheduled job redeploys the site at 6am. For a week everything works. Then the CI provider enables build caching to speed up builds, and from the next morning, the site keeps showing last week's prices after every deploy, though each build reports success. What's wrong? The pages were static, and the build reused cached API responses instead of asking again. The redeploy rebuilt the pages from saved answers, exactly as in this lesson's test. Three fixes: give the price fetch a revalidate interval, so freshness doesn't depend on builds; or revalidate on demand when the stock system changes prices; and if a build must pick up new data, clear .next/cache/fetch-cache in the pipeline first. Then check: after a deploy, does the page's data match the source?

Where you are now

You can fetch from an API on the server with its key kept secret, time out slow requests, check what comes back, and choose, per page, between build-time, every-request and interval fetching, knowing what each does to freshness, load and failures. You've also seen that a rebuild isn't always a refresh. The next lesson adds people to the bakery: logging in with Supabase, and what the browser can and can't be trusted with.

Check yourself

Key terms

• API (application programming interface): a way for programs to ask another system for data or actions, here over HTTP.
• API key: a secret that identifies and authorizes the caller.
• Environment variable: a setting given to a program from outside its code, like BAKEHOUSE_API_KEY.
• server-only: a package that makes the build fail if server code is imported into a client component.
• Error boundary (error.js): what Next.js shows when a page in that folder throws.
• Static, dynamic and revalidated pages: made at build, made per request, or made at build and rebuilt in the background on an interval.
• Stale-while-revalidate: serving a saved copy while fetching a fresh one in the background.
• Build cache: files Next.js keeps between builds to make them faster, including saved fetch responses.
• Validation: checking that data has the shape you expect before using it.

Go deeper

• Next.js: caching and revalidating (opens in a new tab), the fetch reference (opens in a new tab), and CI build caching (opens in a new tab).
• Next.js: environment variables (opens in a new tab).
• Try: change the interval page to revalidate: 60 and put Bakehouse in slow mode. What do visitors see, and how long do they wait?
• Try: write an app/api/revalidate/route.js that calls revalidatePath("/menu"), and call it after changing a price. How fast does the page update now?