REST API Design Guide

Interactive reference and generator for REST API endpoint design best practices

A REST API design guide with best practices for URL structure, HTTP methods, status codes, versioning, and pagination. Enter a resource name to generate example REST endpoints following industry conventions.

REST Endpoint Generator

URL Structure

GOOD
GET /users
GET /users/123
GET /users/123/orders
POST /users
AVOID
GET /getUsers
GET /user/123
GET /getUserOrders/123
POST /createUser
  • Use nouns not verbs — HTTP method IS the verb
  • Use plural resource names consistently (/users not /user)
  • Use lowercase and hyphens for multi-word (/user-profiles not /userProfiles)
  • Keep URLs resource-oriented — hierarchy shows relationships
  • Avoid nesting deeper than 2 levels (/users/123/orders, not /users/123/orders/456/items/789)

HTTP Methods

GET
Retrieve resource(s). Safe and idempotent — no side effects. Use for listing (/users) and fetching (/users/123). Never modify state with GET.
POST
Create a new resource or trigger an action. Not idempotent — calling twice creates two resources. Return 201 Created with Location header.
PUT
Replace a resource completely. Idempotent — calling twice has the same effect. Must include all fields; omitted optional fields default to null.
PATCH
Partially update a resource. Send only the fields to change. Preferred over PUT for most updates — more bandwidth-efficient and explicit.
DELETE
Delete a resource. Idempotent — deleting a non-existent resource should return 404 or 204. Return 204 No Content on success.

How to Design RESTful APIs

REST API design is about consistency and predictability. Well-designed APIs are intuitive — developers can guess endpoints they haven't seen before. This guide covers the most important conventions.

Step 1: Model Your Resources

Identify your core resources (users, orders, products) and their relationships. Resources map directly to database tables or domain objects. Each resource gets its own base path (/users, /orders). Nested resources (orders belonging to users) use hierarchical paths: /users/123/orders.

Step 2: Choose HTTP Methods Correctly

Map operations to HTTP methods: GET for reads, POST for creates, PUT for full replacement, PATCH for partial updates, DELETE for removal. Always return appropriate status codes: 200 for successful GET/PUT/PATCH, 201 for successful POST with Location header, 204 for successful DELETE, 400/422 for validation errors, 401/403 for auth issues.

Step 3: Version Your API

Add versioning from day one: /v1/users. When breaking changes are needed, release /v2/users alongside /v1 — never break existing clients silently. URL path versioning (/v1/, /v2/) is most common for discoverability. Maintain at least one previous version for 6-12 months after releasing a new one.

Step 4: Design Consistent Pagination

Always paginate collection endpoints. Cursor-based pagination (GET /users?cursor=xyz&limit=20) is more stable for real-time data. Offset pagination (GET /users?page=2&limit=20) is simpler for stable datasets. Return pagination metadata: { data: [...], nextCursor: "...", total: 500 }.

More Free Tools

HTTP Status Code Reference

Complete reference for all HTTP response codes

API Rate Limit Calculator

Configure safe rate limits for your API

JWT Decoder

Decode and inspect JWT token claims

CORS Header Generator

Generate correct CORS headers for your API

Regex Tester

Test regex patterns with match highlighting

Frequently Asked Questions

Is this REST API design guide free?

Yes, completely free. No account required.

Should REST API URLs use nouns or verbs?

Always use nouns for resources, never verbs. The HTTP method (GET, POST, DELETE) IS the verb. So /users (not /getUsers), /orders (not /createOrder), /users/123/activate (noun-based sub-resource is acceptable for actions). The URL should describe the resource; the HTTP method describes what to do with it.

Should I use plural or singular resource names?

Use plural nouns consistently: /users (not /user), /orders (not /order), /products (not /product). Plural is the convention because the collection endpoint (/users) and the single resource endpoint (/users/123) share the same base — using plural for both is more consistent than mixing plural collections with singular items.

What is the difference between PUT and PATCH?

PUT replaces the entire resource — you must send all required fields, and any omitted optional fields are set to null/default. PATCH applies a partial update — send only the fields you want to change. For most update operations, PATCH is more appropriate and efficient. Use PUT when you genuinely want to replace a complete document.

What are the main API versioning strategies?

Three common strategies: (1) URL path versioning: /v1/users — most visible, easy to test in browser, hard to maintain. (2) Header versioning: Accept: application/vnd.api.v2+json — clean URLs, harder to test. (3) Query parameter: /users?version=2 — least RESTful. URL path versioning is most common for public APIs because it is the most discoverable.

What is cursor-based pagination and when should I use it?

Cursor-based pagination uses an opaque cursor token (not a page number) to navigate results. GET /users?cursor=eyJpZCI6MTAwfQ&limit=20. It is more stable than offset pagination for real-time data — inserting a new record doesn't shift your page results. Use cursor pagination for feeds, timelines, and frequently-changing data; use offset/page for stable datasets where users need to jump to specific pages.