L2: API Design (REST/GraphQL)

API Design (REST / GraphQL)

In Lesson 5.1, we established the internal standards for generating backend and frontend code. This lesson focuses on the boundary between them: the API. When an autonomous agent builds a full-stack feature, the API acts as the strict contract that keeps the frontend and backend agents perfectly aligned. If you allow Claude to generate API routes haphazardly, your system will rapidly degrade into an unmaintainable web of custom endpoints.

This lesson covers how to instruct Claude to design, document, and implement RESTful and GraphQL APIs using the Contract-First architectural pattern.

1. The "Contract-First" Agentic Workflow

When developers use LLMs, they often prompt: "Write the backend code to fetch a user." The model immediately generates the routing logic, the database query, and the JSON response simultaneously.

The Architectural Vulnerability: If you skip the design phase, the generated API will lack consistency. It might use GET /getUserById instead of GET /users/:id.

The Contract-First Solution:

You must enforce Plan Mode. Before Claude writes a single line of backend or frontend code, it must generate the API specification.

For REST: Instruct Claude to generate a strict OpenAPI (Swagger) YAML specification.
For GraphQL: Instruct Claude to generate the .graphql schema definition (Types, Queries, Mutations).
The Benefit: Once human architects approve the generated contract, you can parallelize the rest of the workflow. You pass the exact same OpenAPI spec to the Backend Agent (to write the controllers) and the Frontend Agent (to write the fetch logic), ensuring mathematically perfect alignment.

2. RESTful Generation Standards

If your enterprise utilizes REST, you must establish strict guardrails in your CLAUDE.md to prevent the model from inventing non-standard RPC-style endpoints (like POST /deleteUser).

Key Constraints for Claude:

Resource Naming: "API paths must use plural nouns, not verbs (e.g., /users, not /getUsers)."
HTTP Verbs: "Strictly map CRUD operations to POST, GET, PUT/PATCH, and DELETE."
Standardized Payloads: "All API responses must wrap data in a data object. All list endpoints must include a meta object with pagination cursors (limit, offset, total)."
Error Schemas: Referencing Module 2, explicitly tell Claude to use your standardized structured error payload for all 4xx and 5xx responses.

3. GraphQL Generation Standards

GraphQL gives clients massive flexibility, but it introduces severe performance risks if the backend agent writes inefficient resolvers. LLMs are notoriously prone to writing resolvers that trigger the N+1 Query Problem (executing a separate database query for every item in a list).

Key Constraints for Claude:

Schema Design: "Group related mutations logically. Do not create massive, monolithic mutation inputs; use granular, specific inputs (e.g., UpdateUserEmailInput instead of a generic UpdateUserInput)."
Resolver Efficiency (The N+1 Fix): "You are strictly forbidden from executing direct database queries inside nested field resolvers. You MUST use the DataLoader pattern (or your framework's equivalent) to batch and resolve nested relationships."
Depth Limiting: "When generating the GraphQL server configuration, explicitly include query depth limits to prevent malicious nested queries."

4. Handling Versioning and Backward Compatibility

Agents are extremely eager to "fix" or "optimize" things. If you assign Claude to add a new field to an existing API, it might decide to rename other fields or restructure the payload to make it "cleaner."

The Architectural Danger: This will instantly break any existing mobile apps or frontend clients relying on the old structure.

The "Append-Only" Prompting Pattern:

When instructing an agent to modify an existing API contract, you must establish an absolute boundary:

"You are modifying a production API. You must follow the 'Append-Only' rule. You may add new routes, new GraphQL fields, or new JSON keys. You are STRICTLY FORBIDDEN from deleting, renaming, or changing the data type of any existing fields. If an existing field is deprecated, mark it with the@deprecated directive, but do not remove it."

5. Automated API Documentation

APIs are useless if human developers (or other agents) don't know how to use them. Because LLMs excel at synthesis, documentation generation should be fully automated in your SDLC pipeline.

The Workflow: Whenever Claude finalizes a backend controller, trigger a secondary prompt: "Read this controller code. Extract all expected headers, query parameters, path variables, and payload shapes. Generate a complete Markdown documentation page includingcurl examples for successful requests and common errors." * This ensures that your developer portals are mathematically synchronized with your actual backend code, eliminating the common enterprise problem of stale API docs.