REST API Design: 7 Mistakes AI-Generated Code Makes (and How to Fix Them)

AI tools can write a working REST API in minutes. The problem: "working" and "production-ready" are not the same thing.

GitHub Copilot, Claude, ChatGPT — these tools write millions of API endpoints every day. Most of them pass a basic smoke test. Many of them fail in production. At Groovy Web, we review AI-generated APIs as part of every engagement, and we see the same seven mistakes appear with striking regularity.

This guide documents every one of them. Each mistake includes why AI generates it, what breaks in production, and the exact code fix your team should apply.

Why This Matters Right Now

AI code generation is no longer an experiment — it is the default workflow for a growing share of engineering teams. GitHub Copilot alone reports over 1.3 million paid subscribers, and that figure does not account for the millions using Claude, ChatGPT, Cursor, or Amazon CodeWhisperer daily.

The core problem is not that AI is bad at writing code. The problem is that LLMs are trained on all of the internet's existing code — including the tutorials, the Stack Overflow snippets, the five-year-old blog posts that predate modern security standards. AI does not distinguish between authoritative patterns and outdated anti-patterns. It replicates both with equal confidence.

The result: teams using AI-generated APIs without structured human review gates see measurably higher API-related incidents in production. The code looks syntactically correct. The tests pass. The endpoints respond. But the design decisions underneath are quietly waiting to cause problems at scale.

Understanding the seven most common failure modes gives your team the vocabulary to catch them in review — and the code patterns to fix them before a single byte hits production.

Mistake 1: Using Verbs in Endpoint Paths

This is the most visible signal that AI generated your API without senior review. REST is a resource-oriented architecture. URLs identify resources, not actions. The HTTP method (GET, POST, PUT, DELETE) is the verb. The path is the noun.

AI tools are trained on enormous volumes of tutorial code where verbs in paths are common — because tutorial authors optimise for clarity at a glance, not for design correctness. The AI reproduces this pattern faithfully.

What AI Generates

// AI-generated endpoint structure — common in tutorials, wrong in production
GET  /getUser/:id
POST /createOrder
PUT  /updateProduct/:id
DELETE /deleteProduct/:id
POST /searchUsers
GET  /fetchAllOrders

What Production APIs Should Look Like

// Correct REST resource naming
GET    /users/:id          // retrieve a user
POST   /users              // create a user
PUT    /users/:id          // replace a user
PATCH  /users/:id          // partially update a user
DELETE /users/:id          // delete a user

GET    /orders             // list orders
POST   /orders             // create an order
GET    /orders/:id         // retrieve a specific order

// Search uses query parameters, not a separate verb endpoint
GET    /users?query=john&role=admin&limit=20

How to Enforce This Automatically

Add a path-naming lint rule to your project. For Node.js projects using ESLint, the eslint-plugin-rest package flags verb-in-path violations. Alternatively, define a custom rule in your linter configuration that rejects paths matching /^/?(get|post|create|update|delete|fetch|search|list)[A-Z]/.

OpenAPI Spectral rulesets can also enforce this at the API spec layer before any code is written — which is the correct place to catch it.

Mistake 2: Returning HTTP 200 for Everything (Including Errors)

This one causes the most downstream damage. When every response carries a 200 status code, every consumer — API clients, mobile apps, monitoring systems, alerting tools — must parse the response body to determine whether a request succeeded. This defeats the entire purpose of HTTP status codes and breaks every standard HTTP-aware tool in your infrastructure.

AI generates this pattern because a large fraction of tutorial code takes the shortcut of returning { status: "error", message: "..." } with a 200 OK. It is faster to write, easy to demonstrate, and completely wrong for production systems.

What AI Generates

// AI-generated error handling — looks fine, breaks everything
app.get('/users/:id', async (req, res) => {
  const user = await db.users.findById(req.params.id);
  if (!user) {
    return res.status(200).json({ status: 'error', message: 'User not found' });
  }
  return res.status(200).json({ status: 'success', data: user });
});

Correct HTTP Status Code Usage

// Production-correct error handling in Express
app.get('/users/:id', async (req, res) => {
  try {
    const user = await db.users.findById(req.params.id);

    if (!user) {
      return res.status(404).json({
        error: 'not_found',
        message: 'User not found',
        requestId: req.id,
      });
    }

    return res.status(200).json({ data: user });
  } catch (err) {
    logger.error('Failed to fetch user', { userId: req.params.id, error: err });
    return res.status(500).json({
      error: 'internal_error',
      message: 'An unexpected error occurred',
      requestId: req.id,
    });
  }
});

The Status Codes Every REST API Must Use Correctly

The 401 vs 403 distinction matters specifically. Returning 403 when a user is not authenticated tells the client "you are authenticated but forbidden" — which leaks information. Return 401 when the identity is unknown, 403 when the identity is known but lacks permission.

Mistake 3: No Pagination on List Endpoints

AI generates GET /users and returns every row in the table. In development this is fine. In production with 500,000 users it causes timeouts, memory exhaustion, and a very bad day for your database connection pool.

AI omits pagination because the example data in training datasets is small. The problem is invisible until you run it against real volume. By then, the pattern is embedded in the codebase and fixing it is a breaking API change.

What AI Generates

// AI-generated list endpoint — will fail at scale
app.get('/users', async (req, res) => {
  const users = await db.users.findAll(); // returns 500,000 rows
  return res.status(200).json({ data: users });
});

Option A: Cursor-Based Pagination (Recommended for Large Datasets)

// Cursor-based pagination — performant at any scale
app.get('/users', async (req, res) => {
  const limit = Math.min(parseInt(req.query.limit) || 20, 100);
  const cursor = req.query.cursor || null;

  const query = db.users
    .orderBy('created_at', 'desc')
    .limit(limit + 1); // fetch one extra to determine hasMore

  if (cursor) {
    const decodedCursor = Buffer.from(cursor, 'base64').toString('utf8');
    query.where('created_at', '<', decodedCursor);
  }

  const users = await query;
  const hasMore = users.length > limit;
  const data = hasMore ? users.slice(0, limit) : users;

  const nextCursor = hasMore
    ? Buffer.from(data[data.length - 1].created_at.toISOString()).toString('base64')
    : null;

  return res.status(200).json({ data, nextCursor, hasMore });
});

Option B: Offset-Based Pagination (Simpler, Suitable for Smaller Tables)

// Offset-based pagination with total count
app.get('/orders', async (req, res) => {
  const page = Math.max(parseInt(req.query.page) || 1, 1);
  const pageSize = Math.min(parseInt(req.query.pageSize) || 20, 100);
  const offset = (page - 1) * pageSize;

  const [data, total] = await Promise.all([
    db.orders.findAll({ limit: pageSize, offset }),
    db.orders.count(),
  ]);

  return res.status(200).json({
    data,
    total,
    page,
    pageSize,
    totalPages: Math.ceil(total / pageSize),
  });
});

Cursor-based pagination is superior for large, frequently-updated datasets because it avoids the "offset drift" problem — where rows inserted between page requests cause items to appear on two pages or disappear entirely. Use offset pagination when you need a specific page number and your dataset is under ~50,000 rows.

Mistake 4: Missing Rate Limiting

An unprotected API endpoint is trivially DoS-able. A single motivated attacker — or a misconfigured client making recursive calls — can saturate your server, exhaust your database connection pool, and trigger your cloud bill alert within minutes. AI generates the business logic for your endpoints but treats rate limiting as someone else's problem.

Rate limiting is not just a security control. It is a reliability control. It protects every other user of your API when one client misbehaves.

Express Rate Limiter Implementation

import rateLimit from 'express-rate-limit';
import RedisStore from 'rate-limit-redis';
import { createClient } from 'redis';

const redisClient = createClient({ url: process.env.REDIS_URL });
await redisClient.connect();

// Global rate limit — applied to all routes
const globalLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 500,                  // 500 requests per window per IP
  standardHeaders: true,     // Return rate limit info in headers
  legacyHeaders: false,
  store: new RedisStore({ sendCommand: (...args) => redisClient.sendCommand(args) }),
  handler: (req, res) => {
    res.status(429).json({
      error: 'rate_limit_exceeded',
      message: 'Too many requests. Please slow down.',
      retryAfter: Math.ceil(req.rateLimit.resetTime / 1000),
    });
  },
});

// Stricter limit for auth endpoints
const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 10,  // 10 login attempts per 15 minutes per IP
  standardHeaders: true,
  legacyHeaders: false,
  store: new RedisStore({ sendCommand: (...args) => redisClient.sendCommand(args) }),
  handler: (req, res) => {
    res.status(429).json({
      error: 'too_many_login_attempts',
      message: 'Too many login attempts. Try again in 15 minutes.',
      retryAfter: Math.ceil(req.rateLimit.resetTime / 1000),
    });
  },
});

app.use(globalLimiter);
app.post('/auth/login', authLimiter, loginHandler);
app.post('/auth/signup', authLimiter, signupHandler);

Rate Limit Response Headers

When standardHeaders: true is set, the following headers are returned on every response. Clients should read these to implement respectful back-off behaviour.

• RateLimit-Limit — Total requests allowed in the window
• RateLimit-Remaining — Requests remaining in the current window
• RateLimit-Reset — Unix timestamp when the window resets
• Retry-After — Seconds until the client may retry (on 429 responses)

Use Redis-backed storage in production. In-memory rate limit stores reset on server restart and do not share state across multiple instances — both of which defeat the purpose entirely in a horizontally-scaled deployment.

Mistake 5: Insecure Direct Object References (IDOR)

This is the most dangerous mistake on this list. It appears in the OWASP API Security Top 10 as API1:2023 — Broken Object Level Authorization — and it is the most common vector for data breaches in REST APIs.

AI generates endpoints that accept an ID from the URL, fetch the corresponding record, and return it. What AI almost never generates is the authorization check: does the authenticated user actually have permission to access this specific record?

What AI Generates

// AI-generated order endpoint — IDOR vulnerability
app.get('/orders/:orderId', authenticate, async (req, res) => {
  const order = await db.orders.findById(req.params.orderId);

  if (!order) {
    return res.status(404).json({ error: 'not_found', message: 'Order not found' });
  }

  // BUG: Any authenticated user can read any order by changing the orderId
  return res.status(200).json({ data: order });
});

In this pattern, every authenticated user can read every other user's orders simply by incrementing the orderId in the URL. If your order IDs are sequential integers (another common AI choice), an attacker can enumerate your entire order history in minutes.

The Fix: Always Check Ownership

// Correct: ownership check on every object-level access
app.get('/orders/:orderId', authenticate, async (req, res) => {
  const order = await db.orders.findById(req.params.orderId);

  if (!order) {
    return res.status(404).json({ error: 'not_found', message: 'Order not found' });
  }

  // Authorization check: does this user own this order?
  if (order.userId !== req.user.id) {
    // Return 403, not 404 — 404 would leak that the order exists
    // For truly sensitive resources, returning 404 is acceptable to prevent enumeration
    return res.status(403).json({
      error: 'forbidden',
      message: 'You do not have permission to access this resource',
      requestId: req.id,
    });
  }

  return res.status(200).json({ data: order });
});

// Better pattern: scope all queries to the authenticated user from the start
app.get('/orders/:orderId', authenticate, async (req, res) => {
  // Query includes userId in the WHERE clause — SQL cannot return other users'' data
  const order = await db.orders.findOne({
    where: { id: req.params.orderId, userId: req.user.id },
  });

  if (!order) {
    return res.status(404).json({ error: 'not_found', message: 'Order not found' });
  }

  return res.status(200).json({ data: order });
});

The second pattern — scoping the database query to the authenticated user — is more robust because authorization cannot be accidentally omitted later. Even if a developer forgets the ownership check in business logic, the database layer enforces it.

Use non-sequential UUIDs as your resource identifiers. Sequential integer IDs make enumeration attacks trivially easy. UUIDs do not prevent IDOR but they make it significantly harder to exploit.

Mistake 6: Exposing Internal Fields and Stack Traces

AI returns what the database gives it. When you ask an AI to write a user endpoint, it typically returns the full ORM model object — including password hashes, internal flags, administrative fields, and any other column that happens to be in the table. Stack traces in error responses are equally common and equally dangerous, because they reveal your server framework, file paths, and internal architecture to anyone who can trigger a 500 error.

What AI Generates

// AI-generated response — exposes internal fields
app.get('/users/:id', authenticate, async (req, res) => {
  const user = await db.users.findById(req.params.id);
  // Returns: id, email, password_hash, salt, internal_notes,
  //          admin_flags, stripe_customer_id, is_test_account...
  return res.status(200).json({ data: user });
});

// AI-generated error handler — exposes stack trace
app.use((err, req, res, next) => {
  res.status(500).json({ error: err.message, stack: err.stack });
});

The Fix: Response Serialization with Whitelisted Fields

// DTO pattern — define exactly what each endpoint returns
const userPublicFields = (user) => ({
  id: user.id,
  email: user.email,
  firstName: user.firstName,
  lastName: user.lastName,
  avatarUrl: user.avatarUrl,
  createdAt: user.createdAt,
  // password_hash, salt, internal_notes, admin_flags — never included
});

const userPrivateFields = (user) => ({
  ...userPublicFields(user),
  phoneNumber: user.phoneNumber,
  billingAddress: user.billingAddress,
  // stripe_customer_id, is_test_account — still never included
});

app.get('/users/:id', authenticate, async (req, res) => {
  const user = await db.users.findById(req.params.id);
  if (!user) return res.status(404).json({ error: 'not_found' });

  // Return different field sets based on who is asking
  const isSelf = user.id === req.user.id;
  const serialized = isSelf ? userPrivateFields(user) : userPublicFields(user);

  return res.status(200).json({ data: serialized });
});

// Production error handler — never expose stack traces
app.use((err, req, res, next) => {
  // Log the full error internally for your team
  logger.error('Unhandled error', {
    requestId: req.id,
    method: req.method,
    path: req.path,
    error: { message: err.message, stack: err.stack },
  });

  // Return a safe error to the client
  const isProd = process.env.NODE_ENV === 'production';
  res.status(err.statusCode || 500).json({
    error: err.code || 'internal_error',
    message: isProd ? 'An unexpected error occurred' : err.message,
    requestId: req.id,
  });
});

Libraries like class-transformer (TypeScript/Node) or marshmallow (Python) provide decorator-based serialization that makes this pattern explicit and enforceable at compile time — the right tool for teams building APIs at scale.

Mistake 7: No Request Validation

AI trusts every byte of the incoming request. It reads from req.body, req.params, and req.query directly, without checking types, required fields, string lengths, value ranges, or format constraints. This creates two categories of failure: reliability failures (unexpected data causes runtime errors) and security failures (malicious data exploits the lack of validation).

What AI Generates

// AI-generated handler — no validation, trusts all input
app.post('/users', async (req, res) => {
  const { email, name, age, role } = req.body;
  // What if email is undefined? What if role is 'admin'?
  // What if age is -99999? What if name is 5,000 characters?
  const user = await db.users.create({ email, name, age, role });
  return res.status(201).json({ data: user });
});

The Fix: Schema Validation with Zod

import { z } from 'zod';

// Define the schema — this is your contract for what the endpoint accepts
const createUserSchema = z.object({
  email: z.string().email('Invalid email format').max(255),
  name: z.string().min(1, 'Name is required').max(100),
  age: z.number().int().min(13).max(120).optional(),
  role: z.enum(['viewer', 'editor', 'manager']), // never trust role from client
  // 'admin' is not an option — privilege escalation prevented at schema level
});

// Reusable validation middleware
const validate = (schema) => (req, res, next) => {
  const result = schema.safeParse(req.body);

  if (!result.success) {
    const fieldErrors = result.error.issues.reduce((acc, issue) => {
      const field = issue.path.join('.');
      acc[field] = issue.message;
      return acc;
    }, {});

    return res.status(400).json({
      error: 'validation_failed',
      message: 'Request validation failed',
      fields: fieldErrors,
      requestId: req.id,
    });
  }

  // Replace req.body with the validated + type-coerced data
  req.body = result.data;
  next();
};

app.post('/users', validate(createUserSchema), async (req, res) => {
  // req.body is now guaranteed to match the schema
  const user = await db.users.create(req.body);
  return res.status(201).json({ data: userPublicFields(user) });
});

What Good Validation Covers

• Types — Is the field a string, number, boolean, or array?
• Required fields — Are all mandatory fields present?
• String constraints — Min/max length, regex format (email, phone, slug)
• Numeric ranges — Min/max values, integer vs float
• Enum values — Only allow specific values for fields like role, status, type
• Nested objects — Validate the shape of embedded objects, not just top-level fields
• Arrays — Min/max length, type of each element

Return field-level error messages in your 400 response. Telling a client "Request is invalid" without specifying which field is invalid is the API equivalent of a form that clears all fields on submission — technically correct, genuinely unhelpful.

The Fix: Human Review Gates in AI-First Development

The seven mistakes above are not random. They are predictable, consistent, and almost entirely avoidable with a structured review process. At Groovy Web, every API produced by our AI Agent Teams passes through five automated checks before a human engineer sees it — and human approval is still required before any code reaches production.

The Five Automated Checks in Every PR

• Security scan — Static analysis flags IDOR patterns, exposed stack traces, and missing authentication middleware using Semgrep rules tuned for REST APIs
• API lint — Spectral rules validate path naming conventions, status code correctness, and OpenAPI spec completeness
• Test coverage gate — PRs below 80% coverage on new API routes are blocked automatically
• Error pattern check — Grep-based scan catches res.status(200).json({ status: "error" }) and similar anti-patterns
• IDOR check — Custom rule verifies that every route handler with a dynamic path segment (:id, :orderId) contains an ownership assertion or calls a scoped query helper

Why Human Approval Is Still Required

Automated checks catch the patterns. Human review catches the intent. An automated tool can verify that a rate limiter middleware is present. It cannot verify that the rate limits are calibrated correctly for the business context. A scanner can detect a missing authorization check. It cannot reason about whether the data model itself creates authorization boundaries that need protecting.

AI Agent Teams with human review gates are not slower than pure AI generation. In our deployments, the review gate adds 30-60 minutes to a feature cycle that previously took days. The tradeoff is unambiguously positive.

AI-Generated vs AI-First With Review: Side by Side

Best Practices: Getting AI APIs Right the First Time

The seven mistakes above are fixable after the fact, but it is significantly cheaper to prevent them. Here is what the best AI-First engineering teams do differently.

Start With an OpenAPI Spec

Generate the OpenAPI specification before generating any code. Prompt your AI with the resource model, operations, and constraints first. Let it produce a openapi.yaml. Run Spectral against that spec. Fix the design issues before a single line of implementation code is written. Code is cheap to generate; design is expensive to change.

Use a Security-Focused System Prompt

When prompting AI for API code, include explicit requirements: "Include ownership checks on all object-level endpoints. Use non-sequential UUIDs as IDs. Validate all inputs with Zod. Return only whitelisted fields. Use correct HTTP status codes." AI follows detailed requirements well — it just does not generate them unless asked.

Build a Reusable Middleware Library

Create project-wide middleware for validation, rate limiting, error handling, and authorization. When AI generates a new endpoint, it imports from this library rather than reinventing the pattern. The library encodes your security defaults — AI can build on them without understanding every nuance of why they exist.

Frequently Asked Questions

Should we use REST or GraphQL for AI-generated projects?

REST is the right default for most teams. GraphQL solves a specific problem — flexible, client-driven queries where different consumers need different field shapes. For internal APIs, microservices, or APIs where you control all consumers, REST is simpler to secure (fixed endpoints are easier to rate-limit and audit than arbitrary queries), easier to cache at the HTTP layer, and produces code that AI tools handle reliably. GraphQL introduces N+1 query problems and query depth attacks that require additional tooling to mitigate. Start with REST; move to GraphQL only when you have a concrete need it solves.

How should we handle API versioning?

Use URL-based versioning (/v1/users, /v2/users) rather than header-based versioning. URL versioning is explicit, cacheable, and easy to route in any proxy or API gateway without custom logic. Introduce a new version when you make a breaking change to an existing endpoint — changing a required field, removing a response field, or altering status code semantics. Non-breaking additions (new optional fields, new endpoints) do not require a version bump. Maintain at least one previous version for a documented deprecation window, typically 6-12 months for external APIs.

What is the best authentication pattern for REST APIs — JWT, sessions, or API keys?

Each pattern suits a different use case. Use JWT (short-lived, 15 minutes) with refresh tokens for browser-facing APIs where you want stateless verification and support for multiple servers without shared session storage. Use server-side sessions with Redis for applications where you need the ability to immediately invalidate a session — financial applications, healthcare, or any context where a compromised account needs instant lockout. Use API keys for machine-to-machine integrations and third-party developer access — they are simpler to issue and rotate than OAuth flows. Never use long-lived JWTs without a revocation mechanism; a stolen JWT with a 24-hour expiry is a 24-hour open door.

Can AI generate OpenAPI/Swagger specs automatically, or do they need manual work?

AI can generate a solid first-draft OpenAPI spec from a natural language description of your API. The quality depends heavily on the prompt — include resource names, operations, key fields, authentication method, and error response shapes. What AI consistently gets wrong in specs: missing error response schemas (it documents the happy path, not the error cases), incomplete parameter validation constraints (maxLength, pattern, enum values), and incorrect security scheme definitions. Plan for a 30-60 minute human review pass on any AI-generated spec before using it as the source of truth. Tools like Stoplight or Redocly provide visual editors that make this review faster.

What is the most effective way to test REST API endpoints?

Layer three types of tests. Unit tests cover individual route handlers in isolation — mock the database, test every branch (happy path, not found, unauthorized, validation failure, 500 error). Integration tests run against a real database (use a test database seeded with known data) and verify the full request-response cycle including middleware. Contract tests verify that your API matches its OpenAPI specification — tools like Dredd or Schemathesis auto-generate test cases from your spec and catch undocumented behavior. For security specifically, run OWASP ZAP or Burp Suite against your staging environment before any production deploy. AI can generate unit and integration test cases reliably once given the endpoint specification and the test framework.

When is it acceptable to break REST conventions?

REST is a set of architectural constraints, not a religion. Break them intentionally when you have a concrete reason. Using a POST for a search endpoint is acceptable when the search criteria are complex enough that they cannot fit cleanly in a query string — a JSON body is easier to work with for multi-field, nested filter criteria. Using a non-standard status code is acceptable when your API gateway or SDK requires it. Long-polling or server-sent events are acceptable for real-time features where WebSockets are not available. The key word is intentionally — document the deviation in your API spec, note why it exists, and ensure every consumer is aware. Unintentional REST violations (which is what AI produces) are the ones that cause incidents.

Frequently Asked Questions

Need Help With Your REST API?

Schedule a free consultation with our AI engineering team. We will review your existing endpoints against the seven mistake categories and provide a clear remediation plan with prioritised fixes.

Schedule Free Consultation →

Related Services

• Web Application Development — Production-grade APIs and backends built with AI Agent Teams
• Hire AI Engineers — Starting at $22/hr, with review gates on every PR
• API Architecture Consulting — Design reviews, OpenAPI specs, and security audits

Published: February 2026 | Author: Groovy Web Team | Category: Web App Development