REST API Design Cheat Sheet

Reference for designing clean REST APIs: resource naming, HTTP methods, status codes, pagination, versioning, and best practices.

2 PagesIntermediateFeb 25, 2026

Resource Naming Conventions

How to structure clean, predictable URLs.

Nouns, not verbs- Use /users not /getUsers — the HTTP method conveys the action
Plural resource names- /orders not /order for collections
Nesting- /users/42/orders for a sub-resource scoped to a parent
Filtering via query params- /orders?status=shipped&sort=-createdAt
Lowercase, hyphenated- /order-items not /orderItems or /OrderItems
Versioning- /v1/users in the URL, or an Accept header-based scheme

HTTP Methods & Example

Standard CRUD verbs and a request/response example.

http

GET /users              # List users (safe, idempotent)GET /users/42           # Retrieve a single userPOST /users             # Create a new userPUT /users/42           # Replace user 42 entirely (idempotent)PATCH /users/42         # Partially update user 42DELETE /users/42        # Remove user 42 (idempotent)# Example request/responsePOST /users HTTP/1.1Content-Type: application/json{"name": "Ada Lovelace", "email": "ada@example.com"}HTTP/1.1 201 CreatedLocation: /users/42Content-Type: application/json{"id": 42, "name": "Ada Lovelace", "email": "ada@example.com"}

Pagination & Versioning

Offset vs cursor pagination, and two common versioning strategies.

http

# Offset-based paginationGET /orders?limit=20&offset=40# Cursor-based pagination (preferred for large/changing datasets)GET /orders?limit=20&cursor=eyJpZCI6MTAwfQ==# Response includes pagination metadata{  "data": [ ... ],  "meta": { "nextCursor": "eyJpZCI6MTIwfQ==", "hasMore": true }}# Versioning strategiesGET /v1/orders                                       # URI versioningGET /orders   Accept: application/vnd.myapi.v2+json  # header versioning

Best Practices

Habits that keep a REST API consistent and maintainable.

Statelessness- Each request must carry all context needed; no server-side session state
Proper status codes- 201 for creation, 204 for empty success, distinct 400 vs 404
Consistent error format- e.g. { "error": { "code": "...", "message": "..." } } on every endpoint
Idempotency keys- For POST operations that must be safely retried (e.g. payments)
Rate-limit headers- X-RateLimit-Limit / X-RateLimit-Remaining / Retry-After
HATEOAS (optional)- Include hypermedia links so clients can discover related actions

Pro Tip

Design around cacheability from day one — mark idempotent GET responses with proper Cache-Control and ETag headers so clients and CDNs can skip redundant round trips instead of hitting your API every time.

Was this cheat sheet helpful?

GraphQL Cheat Sheet

OAuth & JWT Authentication Cheat Sheet

Explore Topics

#RESTAPIDesign#RESTAPIDesignCheatSheet#WebDevelopment#Intermediate#ResourceNamingConventions#HTTPMethodsExample#PaginationVersioning#Designing#Functions#Networking#APIs#CheatSheet#SkillVeris

Sri Hayavadhana Info-Tech

Professional Web Designing Services