API Design Rules | BeforeMerge

Pricing Blog Contributors Install Guide

Explore
API Design

API Design

v1.0.0

Reviews REST API design for consistency, correctness, and security — covering endpoint naming, input validation, HTTP status codes, pagination, and rate limiting. Poorly designed APIs create integration headaches that compound with every new consumer.

14 rules

3 categories

Security(4)

Validate All Request Input

Validate and sanitize all request input (body, query params, headers) before processing. Unvalidated input is the root cause of injection attacks, data corruption, and crashes from malformed data.

ValidationInjectionsecurity

Architecture(9)

Make POST Creates Idempotent via Idempotency Keys

Accept a client-supplied Idempotency-Key header on create/payment endpoints so retried requests do not create duplicate resources.

Return a Consistent, Structured Error Body

Every error response should share one machine-readable shape (code, message, details) so clients can parse failures uniformly.

Return 201 Created with a Location Header on Resource Creation

On successful creation respond with 201 Created, a Location header pointing to the new resource, and ideally its representation.

Quality(1)

Use Proper HTTP Status Codes

Return semantically correct HTTP status codes (400 for bad input, 401 for unauthenticated, 403 for unauthorized, 404 for missing, 500 for server errors). Using 200 for everything hides errors from monitoring, breaks caching, and makes debugging impossible.

RESTqualityHTTP

Automate API Design checks on every PR

BeforeMerge scans your pull requests against all 14 API Design rules automatically. Get actionable feedback before code ships.

Join Waitlist Browse All Rules

AI-native code review knowledge base. Structured rules that catch what linters miss.

Product

Features
Explore
Pricing
Docs
GitHub

Company

About
Blog
Contributors
Contributing

Legal

Privacy Policy
Terms of Service
MIT License

© 2026 BeforeMerge. Built by

Authenticate and Authorize Every Non-Public Endpoint

Require authentication on all non-public routes and enforce per-resource authorization (object-level) on every request.

CRITICAL

Never Leak Internals or Stack Traces in Error Responses

Return sanitized error messages for 4xx/5xx; log full stack traces server-side only and never expose them to clients.

Implement Rate Limiting

Apply rate limiting to all public-facing API endpoints. Without rate limits, a single attacker can overwhelm your server, exhaust your database connections, or brute-force authentication — taking down the service for all users.

Rate Limitingperformancesecurity

Use HTTP Methods According to Their Semantics

GET must be safe and idempotent, PUT/DELETE idempotent, and POST for non-idempotent creates. Never mutate state on a GET.

Paginate All Collection Endpoints

Return collections in bounded pages with a default and maximum page size, exposing next/prev cursors or links.

Version Your API

Version your API from day one (URL prefix, header, or query param). Without versioning, any breaking change forces all clients to update simultaneously or breaks them without warning.

RESTarchitectureAPI

Use Consistent Naming Conventions

Use plural nouns for collections and one consistent casing (e.g. snake_case or camelCase) for fields across the entire API.

Support Filtering and Sorting via Query Parameters

Expose filtering, sorting, and field selection through query parameters rather than proliferating bespoke endpoints.

Use Resource-Oriented (Noun) URLs

Model endpoints as nouns representing resources, not verbs. Let HTTP methods express the action instead of encoding it in the path.

Features Explore

Rules Skills Knowledge Prompts

Pricing Blog Contributors Install Guide

API Design Review

A review skill for HTTP API endpoints that checks design consistency, input handling, and error communication.

What it covers

Endpoint design — RESTful resource naming, proper HTTP method usage, consistent URL structure
Input validation — schema validation at the boundary, rejecting unknown fields, type coercion risks
Status codes — correct usage of 2xx/4xx/5xx, distinguishing 400 from 422, never returning 200 for errors
Pagination and filtering — cursor vs. offset pagination, consistent query parameter patterns
Rate limiting and auth — rate limit headers, proper 401 vs. 403 usage, API key handling
Error responses — structured error bodies, actionable error messages, no stack traces in production

When to use

Run this when building or modifying API endpoints, especially before publishing APIs that external consumers will depend on.