Interactive Documentation Features

This guide walks through building a REST API while showcasing the interactive components available in Starlight. Components are imported from @astrojs/starlight/components and used directly in your content.

Getting started

1. Set up your project

   Create a new directory and initialize your API project. We will use a simple Node.js setup with Express.

   mkdir my-api && cd my-api
   npm init -y

2. Install dependencies

   Install Express and a few helpful utilities for building a production-ready API.

   npm
   bash npm install express cors helmet morgan
   pnpm
   bash pnpm add express cors helmet morgan
   yarn
   bash yarn add express cors helmet morgan

3. Create the entry point

   Create an index.js file with the basic server setup:

   const express = require("express");
   const cors = require("cors");
   const helmet = require("helmet");
   const morgan = require("morgan");
   
   const app = express();
   
   app.use(cors());
   app.use(helmet());
   app.use(morgan("combined"));
   app.use(express.json());
   
   app.listen(3000, () => {
     console.log("API running on http://localhost:3000");
   });

4. Define your first route

   Add a health check endpoint so monitoring tools can verify the API is running.

   app.get("/health", (req, res) => {
     res.json({ status: "ok", uptime: process.uptime() });
   });

5. Test the API

   Start the server and confirm everything works:

   node index.js
   curl http://localhost:3000/health

Key concepts

Routing

Define endpoints that map HTTP methods and paths to handler functions. Express supports GET, POST, PUT, PATCH, and DELETE out of the box.

Middleware

Functions that run before your route handler. Use them for authentication, logging, input validation, and error handling.

Authentication

Protect your endpoints with API keys, JWT tokens, or OAuth. Always validate credentials in middleware, not in individual route handlers.

Error Handling

Return consistent error responses with appropriate HTTP status codes. A global error handler catches anything your routes miss.

Important notes about API design

Tip

Use plural nouns for resource endpoints. Write /users and /users/123, not /getUser or /user/delete. Let HTTP methods convey the action.

Note

Version your API from day one. Prefix all routes with /v1/ so you can introduce breaking changes under /v2/ without disrupting existing consumers.

Caution

Never trust client input. Always validate and sanitize request bodies, query parameters, and path parameters. Libraries like zod or joi make schema validation straightforward.

Danger

Do not expose stack traces in production. Set NODE_ENV=production and ensure your error handler strips internal details before sending responses. Leaking stack traces reveals file paths, dependency versions, and internal logic to attackers.

Response format conventions

Every endpoint should return a consistent JSON structure. Here is the pattern used throughout this API:

Success response

{
  "status": "success",
  "data": {
    "id": 42,
    "name": "Example Resource",
    "created_at": "2026-03-17T10:00:00Z"
  }
}

Error response

{
  "status": "error",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The 'email' field must be a valid email address.",
    "details": [
      { "field": "email", "issue": "invalid_format" }
    ]
  }
}

List response

{
  "status": "success",
  "data": [
    { "id": 1, "name": "First" },
    { "id": 2, "name": "Second" }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 87
  }
}

Endpoint status reference

When documenting your API, use badges to communicate the stability of each endpoint:

Endpoint	Method	Status
/v1/users	GET	Stable
/v1/users/:id	GET	Stable
/v1/users	POST	Stable
/v1/users/:id/avatar	PUT	Beta
/v1/search	GET	Experimental
/v1/webhooks	POST	New

Client-side interactivity

Starlight with MDX supports embedding framework components directly. This counter is a Solid.js component hydrated on the client:

−0+

Start from a different value by passing the initial attribute:

−10+

This works by importing an Astro wrapper around a Solid.js component with client:visible hydration.

Further reading

Express.js Documentation Official guide and API reference for the Express web framework.

HTTP Status Codes MDN reference for every HTTP status code and when to use each one.

REST API Design Best Practices Comprehensive guide to designing clean, consistent RESTful APIs.

OWASP API Security Top 10 The most critical security risks for APIs, with prevention strategies.