Building REST APIs with AI-Assisted Prompt Workflows

REST APIs follow predictable patterns — routes, validation, business logic, response shapes — which makes them perfect for AI generation. A good prompt produces consistent endpoints across your codebase; a bad one produces a different style of endpoint every time.

1. Introduction

Most REST endpoints are 90% boilerplate: parse the request, validate the input, call the service, shape the response, handle the error. AI can produce that scaffolding in seconds — but only if you give it a clear contract first. This tutorial walks through the route-first prompt pattern: define the contract, then generate the implementation against it.

2. The Concept Explained

A REST endpoint is essentially a small contract between client and server: a method, a path, an input shape, a response shape, and a set of possible status codes. If you describe that contract precisely in the prompt, the AI can fill in the implementation with very little ambiguity.

It is the same skill as writing an OpenAPI spec — but in conversational form. Once you internalise that an endpoint is a contract, your prompts become contract specifications and the AI becomes a very fast junior who writes the implementation underneath.

3. The Problem Without This Technique

The shortcut prompt is to describe the endpoint in a sentence and hope the AI fills the rest in. It will — but every endpoint generated this way will have a different style, different error shape, and different validation strictness.

make an endpoint to create a new order

4. The Solution

Stack: Node.js 20, Express 4, TypeScript strict mode.
Validation: zod 3. Error shape (already used across the codebase):
  { error: { code: string, message: string, details?: unknown } }
Auth: requireUser middleware injects req.user: { id: string; role: 'admin' | 'customer' }.

Build POST /api/orders.

Request body (JSON):
  {
    items: Array<{ productId: string; quantity: number }>,  // 1..50 items
    shippingAddress: {
      line1: string,
      city: string,
      country: string  // ISO 3166-1 alpha-2
    },
    couponCode?: string
  }

Validation rules:
- items non-empty, quantity 1..99 per item
- country is exactly 2 uppercase letters
- couponCode, if present, 4..16 chars, alphanumeric uppercase

Behaviour:
- Authenticated users only (role 'admin' or 'customer')
- Call `await orderService.create(req.user.id, validatedBody)` for business logic
- Service returns an Order or throws OrderServiceError with .code

Responses:
- 201 Created → { order: Order }
- 400 Bad Request → validation error (code: 'INVALID_BODY')
- 401 Unauthorized → no user (handled by middleware, do not duplicate)
- 409 Conflict → service throws code 'OUT_OF_STOCK' (forward message)
- 500 Internal Server Error → unexpected (code: 'INTERNAL_ERROR')

Output: only the route handler file, including the zod schema and a single
exported `router` from `express.Router()`. No tests, no docs.

5. Step-by-Step Breakdown

1. State stack, framework, and shared conventions. Validation library, error shape, auth middleware. Once per chat session is enough.
2. Pin down the route signature. Method, path, what the URL parameters mean.
3. Describe the request shape with types. Required vs optional, min/max, allowed values. Be explicit — vagueness becomes a validation gap.
4. Map each business case to a status code. Success path, validation failure, auth failure, business conflict, server error. This is how you achieve consistency across endpoints.
5. Name the service or helper to call. Don't ask the AI to invent business logic inside the route — tell it which existing service handles it.
6. Specify what to include and exclude. Just the handler? Or also the OpenAPI spec? Tests? Schemas? Clear boundaries prevent scope creep.

Tip: Once one endpoint is set up well, ask the AI to "use this file as a template" when generating the next endpoint. Pasting a reference handler from your own codebase locks in the team's style.

6. Practice Exercises

Generate the OpenAPI 3 spec fragment for this endpoint, matching the implementation exactly.

7. Key Takeaways