preventing 404s by design

As an APIary platform that values "Lambo not Honda" UI/UX quality, we strive to provide a seamless user experience free from dead ends and broken links. In this article, we'll explore strategies for preventing 404 errors, ensuring our platform remains intuitive and efficient.

Link Auditing in CI

To catch potential 404s early on, we integrate link auditing into our Continuous Integration (CI) pipeline. This involves:

1. Crawling the application's URLs to identify all links.
2. Verifying the existence of each linked resource (e.g., images, stylesheets, scripts).
3. Reporting any broken links for review and repair.

Using a tool like link-checker (a Node.js library), we can automate this process:

const linkChecker = require('link-checker');

// Specify URLs to crawl
const urls = ['https://example.com/path1', 'https://example.com/path2'];

// Perform link auditing
linkChecker.crawl(urls, (err, results) => {
  if (err) console.error(err);
  // Review and report broken links
});

Broken-Link Checks

Regularly scheduled checks ensure our platform remains free from broken links. We use a headless browser like Puppeteer to simulate user interactions:

const puppeteer = require('puppeteer');

// Launch headless browser instance
(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  // Navigate to URL and inspect links
  await page.goto('https://example.com/path');
  const links = await page.$$('a');

  for (const link of links) {
    const href = await link.getProperty('href').then((prop) => prop._remoteObject.value);
    if (!await page.waitForNavigation({ url: href })) {
      // Report broken link
    }
  }

  await browser.close();
})();

Route Generation from Sources of Truth

To minimize the likelihood of 404s, we generate routes based on authoritative sources of truth (e.g., database schema, API definitions). This ensures our routing configuration accurately reflects the application's structure:

// Example using Express.js and a MongoDB database
const express = require('express');
const mongoose = require('mongoose');

const app = express();
const db = mongoose.connect('mongodb://localhost/example');

app.get('/users/:id', (req, res) => {
  const id = req.params.id;
  // Fetch user data from database using the generated route
});

Fallback Redirects

When a requested resource is not found, we employ fallback redirects to provide an alternative experience:

// Example using Express.js and a catch-all redirect
app.use((req, res, next) => {
  const path = req.path;
  // Check if URL matches a known route or resource
  if (!path.startsWith('/api')) {
    // Redirect to a default page (e.g., homepage)
    return res.redirect('/');
  }
  next();
});

By incorporating these strategies into our APIary platform, we significantly reduce the occurrence of 404 errors and create a more polished user experience.