# API Design Best Practices Cheat Sheet

> A ten-point reference checklist for designing clean and reliable REST APIs.

This reference checklist outlines ten foundational best practices for building RESTful APIs, created by Pratham Kumar. It covers key architecture decisions including URL naming conventions, HTTP method usage, versioning, status codes, error structures, security, rate limiting, and caching.

## The framework

1. Use RESTful URLs — make endpoints clear, meaningful, follow REST conventions. Example: /users/{id} instead of /getUserById.
2. Implement Proper HTTP Methods — correct verbs for the action. GET for reading, POST for creating, PUT/PATCH for updating, DELETE for removing.
3. Version Your API — include a version for backward compatibility. /v1/products, or headers like Accept: application/vnd.api+json;v=1.
4. Provide Pagination for Large Responses — use ?page=1&limit=10 to return paginated responses.
5. Use Consistent Error Handling — structured, informative error messages with proper status codes; return JSON with details, e.g. 404 for not found, 400 for validation issues.
6. Secure Your API with Authentication and Authorization — implement OAuth, JWT, or API keys; require Authorization headers with tokens.
7. Return the Right Status Codes — 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error.
8. Document Your API — detailed docs with endpoint descriptions, parameters, sample responses; use Swagger or Postman for interactive docs.
9. Rate Limit Your API — indicate limits via headers: X-RateLimit-Limit, X-RateLimit-Remaining; return 429 Too Many Requests when exceeded.
10. Use Caching to Optimize Performance — use Cache-Control headers to specify how long clients can cache responses.

## What it is for

- Review an API schema or design spec before starting implementation
- Audit existing endpoints for consistency in URL naming, error formats, and status codes
- Onboard junior backend developers to standard REST conventions

## Key points

- RESTful URL conventions using resource nouns instead of actions
- Standard HTTP verb mapping (GET, POST, PUT/PATCH, DELETE)
- API versioning strategies via path prefixes or Accept headers
- Query-based pagination patterns for large collections
- Standardized JSON error response structures and status code matching
- Auth implementation guidance using tokens and authorization headers
- Operational safeguards including rate limiting headers and Cache-Control

## Pricing

Free

## Details

- Type: Framework
- Category: [Development](https://xiry.app/topics/development.md)
- Open source: no
- Platforms: other
- For: Backend engineers and API designers
- Tags: api, rest, backend, architecture, cheatsheet, bestpractices

## Why it was saved

- [@Prathkum, 17 September 2024](https://x.com/Prathkum/status/1836044198341923031): A complete reference checklist for designing and shipping a well-behaved API: URLs, verbs, versioning, pagination, errors, auth, status codes, docs, rate limiting, caching.

## Related

- [Parse](https://xiry.app/resources/parse): Turn any website into a structured REST API using natural language (Web app, Freemium)
- [Stripe Bill for LLM Tokens](https://xiry.app/resources/stripe-bill-for-llm-tokens): Usage-based billing infrastructure for charging end users and reselling LLM tokens. (Web app, Paid)
- [Accessing X Internal API via Session Tokens](https://xiry.app/resources/accessing-x-internal-api-via-session-tokens): Tutorial explaining session token replay for internal X API access (Framework, Free)
- [AI/ML API](https://xiry.app/resources/ai-ml-api): Single API and playground for hundreds of multimodal AI models (Web app, Paid)
- [Bytez](https://xiry.app/resources/bytez): Unified serverless API to discover and run open and closed AI models (Web app, Freemium)
- [Cloudflare /crawl Endpoint](https://xiry.app/resources/cloudflare-crawl-endpoint): Single API endpoint to crawl entire websites to Markdown, HTML, or JSON (Tip, Freemium)

Updated 11 October 2026. Page: https://xiry.app/resources/api-design-best-practices-cheat-sheet

Make your own library: Xiry takes your saved reels, tweets, Reddit bookmarks and Watch Later videos, makes them searchable and pulls the useful stuff out, like this library. It's invite-only for now; join the waitlist at https://xiry.app/#waitlist.