---
title: API Design Principles
category: product
entity_type: skill
price: $15
canonical: https://forgehouse.ai/skills/api-design-principles/
lang: en
hreflang_alt: https://forgehouse.ai/tr/skiller/api-design-principles/
last_updated: 2026-06-20
---

# API Design Principles

> Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable…

A design-standards reference for building REST and GraphQL APIs that developers love to consume and teams can maintain for years. It grounds every choice in contract-first design, idempotency, least astonishment, and layered defense: covering resource modeling, pagination, error formats, versioning, and the N+1 problem with worked examples in both paradigms.

## Use cases
- Designing a new REST or GraphQL API before any code is written
- Establishing API design standards and conventions for a team
- Reviewing an API specification before implementation begins
- Choosing and implementing an API versioning strategy
- Designing cursor-based pagination and consistent error responses
- Preventing the N+1 problem in GraphQL resolvers with DataLoaders

## Benefits
- APIs that feel intuitive, cutting integration friction and support tickets
- Fewer breaking changes thanks to contract-first specs and versioning discipline
- Consistent error and pagination contracts across every endpoint
- Reliable mutations via idempotency keys on critical operations

## What’s included
- REST resource-collection design with correct HTTP method semantics
- GraphQL schema-first patterns, Relay-style pagination, and resolver design
- Three versioning strategies (URL, header, query parameter) with trade-offs
- Consistent error-response and status-code conventions
- HATEOAS hypermedia and DataLoader N+1-prevention patterns
- A common-pitfalls catalog covering over-fetching, tight coupling, and missing limits

## Who it’s for
API designers, backend leads, and architects setting the standards that other developers will build against.

## How it runs
The contract comes before the code. An OpenAPI spec or GraphQL schema gets locked first, and every endpoint is then held to the same shapes and semantics:
1. Contract first: the OpenAPI 3.1 spec (or GraphQL schema) is written before code. Request and response shapes, status codes and the error format are locked, so frontend and backend teams build against the same contract in parallel.
2. Models resources as nouns with HTTP verbs doing the work: GET/POST /api/users, nested /users/{id}/orders. Action-verb endpoints like /createUser or /getUserById are rejected at review.
3. Standardizes the repeating contracts: one pagination pattern (page and page_size with totals, or Relay-style cursors in GraphQL), one error envelope with error, message and details, and consistent status code semantics across every endpoint.
4. Adds idempotency keys to mutations following the Stripe model and picks a versioning strategy up front; a breaking change means a major version with a minimum 90-day sunset notice.
5. On the GraphQL side works schema-first: typed connections for pagination, mutation payloads that carry structured errors, and every relationship resolver routed through a DataLoader to kill N+1 queries.
6. Closes with the defense-in-depth review: auth middleware, per-IP rate limiting, field-level input validation and output encoding checked as four independent layers that fail separately.

## FAQ
### We're split between REST and GraphQL, does this only help one of them?
It covers both paradigms and the choices each forces: resource modeling, pagination, error formats, versioning. The shared principles (contract-first design, idempotency, least astonishment) apply whichever you pick.

### Is this just one team's opinion on naming, or decisions I can defend?
Every convention is tied back to a reason: least astonishment for consumers, layered defense for safety, idempotency for retries. You're not adopting taste, you're adopting trade-offs you can explain in a review.

### Does it produce my OpenAPI spec or schema?
No, it's a design-time reference for making the decisions before code, not a generator. It tells you what a good contract looks like; writing and serving that contract stays on your side.

## Price
$15, one-time, no subscription. VAT included.

Related guide: [AI code review and developer workflow](https://forgehouse.ai/guides/ai-code-review/)