SampleAPIs

The SampleAPIs documentation is organized into several functional areas:

The server is built using the following technologies:

• Express 5: Handles routing and middleware. Note that rejected async handlers flow to the central error handler natively.
• helmet: Provides security headers (CSP is disabled for legacy Pug pages).
• cors: Configured with permissive CORS to support its role as a public API.
• express-rate-limit: Used for request throttling.
• morgan: Handles request logging (dev mode for local development, combined for production).
• pug: Used for templating legacy site pages and reset/create pages.
• jest & nodemon: Dev-only tools for testing and file-watching restarts.

Note: The server intentionally uses no database and no ORM; it relies on flat JSON files.

The client application is built with the following technologies:

• React 19 + TypeScript: Core UI framework.
• Vite 8 (with SWC plugin): Build tool and development server.
• TanStack Router: Provides file-based routing with automatic code-splitting.
• TanStack Query: Manages server state and caching.
• CodeMirror 6: Powers the Playground editor.
• Fontsource: Provides self-hosted Roboto and Montserrat Alternates fonts.
• oxlint: Used for linting (replaces ESLint).

When using or building on SampleAPIs, keep these operational traits in mind:

• No Authentication: The service is designed for learning; anyone can perform read and write operations without credentials.
• Rate Limiting: To prevent abuse, the service employs two request limiters.
• Self-healing: The system is designed to be self-healing by periodically restoring data from the .json.backup files.
• Legacy Routes: The server includes a legacy Pug-rendered site accessible at the / route.

The Query Builder is a purely client-side implementation hosted within the APIDetails.tsx page. It follows this data flow:

1. Field Discovery: The system fetches a sample of the active endpoint (using ?_limit=N) and uses a shared utility deriveShape() to identify available field paths and types.
2. User Input: Users interact with a Field Picker, Filter rows, Sort controls, and Pagination controls.
3. State Management: All inputs update a single state object containing filters, q, sort, and pagination.
4. URL Generation: A pure function buildQueryString(state) converts the state into a valid URL string, which is displayed in a live URL bar.
5. Preview: A debounced fetch (~400ms) is triggered by URL changes to preview results using the JsonTree component. The total record count is displayed using the X-Total-Count header.

To implement copy-only snippets (curl, Python, Node) alongside existing runnable JavaScript snippets, a new parallel export COPY_SNIPPETS is used. This prevents accidental mixing of runnable and copy-only code.

Each entry in COPY_SNIPPETS represents a language and contains multiple variants (e.g., GET, GET with query, POST) that use a build(url) function to interpolate the active endpoint URL.

Constraints for POST snippets:

• Snippet bodies must satisfy the server's shape validation defined in server/utils/verifyData.js.
• Bodies should be generic-but-valid or include a comment noting the expected shape to avoid errors.

// Proposed structure for COPY_SNIPPETS
COPY_SNIPPETS: { 
  id: string, 
  label: string, 
  language: string, 
  variants: { 
    id: string, 
    label: string, 
    build(url: string): string 
  }[] 
}[]

The stack consists of two primary services running within an app-network:

1. server:

   • Runs the Node.js application (sampleapis.js) on port 5555.
   • Installs production dependencies only (npm ci --omit=dev).
   • Runs as an unprivileged node user.
   • While the image defaults to NODE_ENV=production, Docker Compose overrides this to development to enable dev logging via morgan.
   • Includes a healthcheck that performs a wget /health every 10 seconds.

2. client:

   • Builds the application using tsc && vite build.
   • Serves the production bundle using vite preview on port 4444.
   • Dependency Note: The client service is configured to wait and start only after the server service reports a healthy status via its healthcheck.