# API Best Practices

> Apply modern standards and best practices for designing scalable, secure, and maintainable REST APIs.

- Skill: `heldinhow/api-best-practices` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add heldinhow/api-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/heldinhow/api-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: Heldinhow (https://skillmd.com/u/heldinhow)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/heldinhow/api-best-practices

---


# REST API Best Practices

## Overview
Designing a robust REST API is critical for frontend-backend communication and third-party integrations. This skill covers the structural rules, status codes, naming conventions, and security measures essential for building professional APIs. Invoke this skill when architecting a new backend service, refactoring existing endpoints, or reviewing API designs.

## Core Principles
- **Resource-Oriented**: URLs should represent nouns (resources), not verbs (actions).
- **Statelessness**: Each request must contain all the information the server needs to fulfill it. The server should not store request state between calls.
- **Predictability**: A consumer should be able to guess endpoint structures based on existing patterns.
- **Idempotency**: Operations like PUT and DELETE should produce the same result no matter how many times they are called.

## Preparation Checklist
- [ ] Identify the core domain entities that will be exposed as resources.
- [ ] Decide on the API versioning strategy (e.g., URL path `/v1/`, header, or query param).
- [ ] Establish the standardization for response formats (e.g., JSON API standard, wrapper objects).

## Step-by-Step Process
1. **Model Resources**: Define the nouns (e.g., `/users`, `/orders`, `/products`). Use plurals consistently.
2. **Map HTTP Methods**:
   - `GET`: Retrieve a resource or collection.
   - `POST`: Create a new resource.
   - `PUT`: Completely replace an existing resource.
   - `PATCH`: Partially update an existing resource.
   - `DELETE`: Remove a resource.
3. **Structure the URLs**: Use nested structures for relationships, but keep it shallow (max 2 levels deep). Example: `/users/123/orders` is good; `/users/123/orders/456/items/789` is bad.
4. **Define Standard Responses**: Standardize pagination (offset/limit or cursor), sorting, and filtering via query parameters.
5. **Implement Error Handling**: Define a consistent error payload structure (e.g., `{ "error": { "code": 404, "message": "Not found" } }`). Use correct HTTP status codes (2xx for success, 4xx for client errors, 5xx for server errors).
6. **Add Security**: Enforce HTTPS, implement authentication (e.g., JWT, OAuth), and add rate limiting to prevent abuse.

## Do's and Don'ts
- ✅ **Do** use HTTP status codes correctly. Don't return a 200 OK with an error message in the body.
- ✅ **Do** provide pagination for any endpoint that returns a list.
- ❌ **Don't** use verbs in URLs (e.g., use `POST /articles`, not `POST /createArticle`).
- ❌ **Don't** expose internal database IDs if security is a concern; use UUIDs.

## Anti-Patterns
- **The Everything Endpoint**: Creating a single endpoint that returns massive, complex payloads trying to satisfy every frontend requirement in one call.
- **Ignoring Caching**: Failing to use standard HTTP caching headers (ETag, Cache-Control), leading to unnecessary server load.
- **Version Breaking**: Changing the response structure of an existing endpoint without bumping the API version.