Project: a data dashboard from a public JSON API

Understanding Project: a data dashboard from a public JSON API

A dashboard is three stages that should not be mixed: transport (ask the endpoint for bytes and check the HTTP status), transform (fold the raw records into the handful of numbers the panels display), and render (turn one state value into text or DOM). Only the first stage is slow and unreliable, so if the other two are ordinary synchronous functions over plain data you can paste a saved response into them and see the finished dashboard with no network at all. The API's field names are also not your field names; normalising at the boundary means that the day the endpoint renames a field you edit one function instead of hunting through rendering code.

A network read has four outcomes a user can tell apart - still pending, came back empty, failed, and ready - so the dashboard has to be able to draw all four, because a blank panel is indistinguishable from a broken one. Keeping status and data in a single state object and re-rendering the whole panel after each transition means the screen can never be half old numbers and half new ones. The status check matters more than beginners expect: fetch resolves happily for 404 and 500 and rejects only when no HTTP reply arrived at all, so without an explicit throw on !res.ok a JSON error page walks straight into your reducer.

Then there is time. Await orders the statements inside one call, but two calls started by two clicks race each other, and the panel keeps whichever finishes last - which may be the request the user already abandoned. A counter compared just before the write, or an AbortController that cancels the previous request (the aborted fetch then rejects with an AbortError you filter out of the error branch), lets the user's selection rather than network latency decide what is on screen.

// Transport, transform and render kept apart. fetch is a parameter, so the same
// loader runs against a real endpoint or against the fixed stub below.
const payload = {
  results: [
    { country: 'Portugal', city: 'Lisbon', pm25: 18.4 },
    { country: 'Portugal', city: 'Porto', pm25: 12 },
    { country: 'Spain', city: 'Madrid', pm25: 24.6 },
    { country: 'Spain', city: 'Seville', pm25: 21.4 }
  ]
};

const stubFetch = () => Promise.resolve({
  ok: true,
  status: 200,
  json: () => Promise.resolve(payload)
});

async function loadRows(fetchImpl, url) {
  const res = await fetchImpl(url);
  if (!res.ok) throw new Error('HTTP ' + res.status);
  const body = await res.json();
  return body.results;
}

function summarise(rows) {
  const byCountry = new Map();
  for (const row of rows) {
    if (!Number.isFinite(row.pm25)) continue;
    const acc = byCountry.get(row.country) || { stations: 0, total: 0 };
    acc.stations += 1;
    acc.total += row.pm25;
    byCountry.set(row.country, acc);
  }
  return [...byCountry].map(([country, acc]) => ({
    country,
    stations: acc.stations,
    mean: acc.total / acc.stations
  }));
}

function render(state) {
  if (state.status === 'loading') return 'Loading air quality...';
  if (state.status === 'error') return 'Could not load data: ' + state.error;
  if (state.data.length === 0) return 'No stations reported.';
  return state.data
    .map(r => `${r.country}: ${r.stations} stations, mean PM2.5 ${r.mean.toFixed(1)}`)
    .join('\n');
}

async function main() {
  let state = { status: 'loading' };
  console.log(render(state));
  try {
    const rows = await loadRows(stubFetch, '/air?limit=4');
    state = { status: 'ready', data: summarise(rows) };
  } catch (err) {
    state = { status: 'error', error: err.message };
  }
  console.log(render(state));
}

main();

Worked examples

const respond = (status, body) => Promise.resolve({
  ok: status >= 200 && status < 300,
  status,
  json: () => Promise.resolve(body)
});

async function readJson(responsePromise) {
  const res = await responsePromise;
  if (!res.ok) throw new Error('request failed with ' + res.status);
  return res.json();
}

async function run() {
  const cases = [respond(200, { total: 3 }), respond(404, { message: 'no such dataset' })];
  for (const c of cases) {
    try {
      const data = await readJson(c);
      console.log('ok, total =', data.total);
    } catch (err) {
      console.log('caught:', err.message);
    }
  }
}

run();

const delay = (ms, value) => new Promise(resolve => setTimeout(() => resolve(value), ms));

let latestTicket = 0;
let panel = 'empty';

async function selectRange(range, ms) {
  const ticket = ++latestTicket;
  const data = await delay(ms, range + ' totals');
  if (ticket !== latestTicket) {
    console.log('ignored stale response:', range);
    return;
  }
  panel = data;
  console.log('rendered:', panel);
}

selectRange('year', 60);
selectRange('week', 10);

setTimeout(() => console.log('panel still shows:', panel), 120);

const rows = [
  { city: 'Oslo', temp: -3.5 },
  { city: 'Rome', temp: null },
  { city: 'Cairo', temp: 31.5 },
  { city: 'Lima', temp: 'n/a' },
  { city: 'Perth', temp: 22 }
];

const naive = rows.reduce((sum, r) => sum + r.temp, 0) / rows.length;
const usable = rows.filter(r => Number.isFinite(r.temp));
const mean = usable.reduce((sum, r) => sum + r.temp, 0) / usable.length;

console.log('naive mean:', naive);
console.log('usable readings:', usable.length, 'of', rows.length);
console.log('mean temp:', mean.toFixed(1));

Important notes

Common mistakes

Try it yourself