backend-api-design

Backend API Design

Purpose

Design consistent, production-grade REST or GraphQL APIs. Every endpoint must follow the same conventions for URLs, requests, responses, errors, and pagination.

Agent Protocol

Trigger

Exact user phrases: "API design", "REST API", "GraphQL schema", "endpoint design", "API conventions", "URL structure", "HTTP methods", "response format", "API versioning", "pagination", "design an endpoint", "API contract".

Input Context

Before activating, verify:

• The resource or feature being designed is known.
• The tech-spec for the feature exists or the user has described the resource.
• The chosen API style (REST/GraphQL) is known. If not, ask: "REST or GraphQL?"

Output Artifact

No file output unless the user requests it. Produces endpoint specifications as text.

Response Format

For each endpoint:

{method} {path}
Auth: {required/optional/none}
Request: {schema reference}
Response 2xx: {schema reference}
Errors: {list of error codes}

For a full API design, group by resource:

## {resource}
{list of endpoints}

No preamble. No postamble. No explanations. No filler/hedging/transitions. Compress output. No explanations of REST principles.

Completion Criteria

• All resources follow the naming conventions below.
• Every endpoint has: method, path, auth requirement, request schema, response schema, error codes.
• List endpoints are paginated.
• Response envelope is consistent across all endpoints.
• Error responses follow the standard format.
• No verbs in URL paths.

Max Response Length

Per endpoint: 6 lines. Per resource: unlimited.

Architecture Decision Trees

REST vs GraphQL Decision Tree

What is the primary client type?
├── Public API with many consumers
│   ├── REST — broadest compatibility, cache-friendly, CDN-friendly
│   └── GraphQL only if clients need flexible data shapes
├── Single-page application (SPA)
│   ├── REST + BFF — simpler, more performant, better caching
│   └── GraphQL — if client needs to compose multiple resources
├── Mobile application
│   ├── REST + BFF — smaller payloads, server-controlled shapes
│   └── GraphQL — if network round-trips are the bottleneck
└── Service-to-service (internal)
    ├── REST — simple, familiar, good enough
    └── gRPC — if latency-critical or streaming needed