openevidence-local-dev-loop

OpenEvidence Local Dev Loop

Overview

Local development workflow for OpenEvidence clinical decision support API integration. Provides a fast feedback loop with mock evidence queries, citation responses, and clinical summary data so you can build health-tech tools without consuming live API quota. Toggle between mock mode for rapid iteration and sandbox mode for validating against the real OpenEvidence platform. Always use de-identified data in development.

Environment Setup

cp .env.example .env
# Set your credentials:
# OPENEVIDENCE_API_KEY=oe_xxxxxxxxxxxx
# OPENEVIDENCE_BASE_URL=https://api.openevidence.com/v1
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express

Dev Server

// src/dev/server.ts
import express from "express";
import { createProxyMiddleware } from "http-proxy-middleware";
const app = express();
app.use(express.json());
const MOCK = process.env.MOCK_MODE === "true";
if (!MOCK) {
  app.use("/v1", createProxyMiddleware({
    target: process.env.OPENEVIDENCE_BASE_URL,
    changeOrigin: true,
    headers: { Authorization: `Bearer ${process.env.OPENEVIDENCE_API_KEY}` },
  }));
} else {
  const { mountMockRoutes } = require("./mocks");
  mountMockRoutes(app);
}
app.listen(3008, () => console.log(`OpenEvidence dev server on :3008 [mock=${MOCK}]`));

Mock Mode

// src/dev/mocks.ts — realistic clinical decision support responses (de-identified)
export function mountMockRoutes(app: any) {
  app.post("/v1/query", (req: any, res: any) => res.json({
    query: req.body.question,
    answer: "Based on current evidence, first-line treatment for type 2 diabetes includes metformin combined with lifestyle modifications. HbA1c targets should be individualized.",
    citations: [
      { title: "ADA Standards of Care 2025", source: "Diabetes Care", doi: "10.2337/dc25-S009", year: 2025 },
      { title: "Metformin Meta-Analysis", source: "NEJM", doi: "10.1056/NEJMoa2412345", year: 2024 },
    ],
    confidenceScore: 0.92,
  }));
  app.get("/v1/topics", (_req: any, res: any) => res.json([
    { id: "top_1", name: "Diabetes Management", questionCount: 245 },
    { id: "top_2", name: "Hypertension", questionCount: 189 },
    { id: "top_3", name: "Oncology Screening", questionCount: 134 },
  ]));
  app.get("/v1/citations/:doi", (req: any, res: any) => res.json({
    doi: req.params.doi, title: "ADA Standards of Care 2025", abstract: "Annual update to diabetes management guidelines...",
    journal: "Diabetes Care", year: 2025, evidenceLevel: "Level I",
  }));
}

Testing Workflow

npm run dev:mock &                    # Start mock server in background
npm run test                          # Unit tests with vitest
npm run test -- --watch               # Watch mode for rapid iteration
MOCK_MODE=false npm run test:integration  # Integration test against real API

Debug Tips

• Never use real patient data in development — all mock data must be de-identified
• confidenceScore ranges from 0 to 1 — display as percentage in UI
• Citation DOIs may be null for preprints or conference abstracts
• Query responses can be slow (2-5s) on the live API — set appropriate timeouts
• Use topics endpoint to validate query categorization before submitting full queries

Error Handling

Issue	Cause	Fix
401 Unauthorized	Invalid API key	Regenerate at OpenEvidence developer portal
400 Bad Request	Empty or malformed query	Validate question field is non-empty string
422 Unprocessable	Query outside supported medical domains	Check supported topics first
429 Rate Limited	Too many queries per minute	Add backoff, switch to mock mode
ECONNREFUSED :3008	Dev server not running	Run npm run dev:mock first

Resources

• OpenEvidence Platform

Next Steps

See openevidence-debug-bundle.