Prince

The Complete Guide to REST API Design: From Standards to Implementation

Prince Pal
15 min read

A comprehensive guide to designing professional REST APIs with practical examples, covering resource design, HTTP methods, status codes, and best practices for modern backend development.

Table of Contents

API design is one of the most critical skills for backend engineers. Despite years of research and established standards, questions about REST API design continue to puzzle developers: Should URI paths be plural or singular? When should you use PATCH versus PUT? What status codes are appropriate for different scenarios?

This guide will help you understand REST API design from the ground up, providing clear guidelines that eliminate guesswork and let you focus on building great applications.

Understanding REST: A Brief History

The Birth of the Web

In 1990, Tim Berners-Lee launched the World Wide Web project with a simple goal: share knowledge globally. Within a remarkably short time, he invented the foundational technologies we still use today:

  • URI (Uniform Resource Identifier) for addressing resources
  • HTTP protocol for client-server communication
  • HTML for structuring web content
  • The first web server and browser
  • An integrated HTML editor

However, the explosive growth of users soon revealed scalability challenges that threatened the web's future.

Roy Fielding's Solution

By 1993, Roy Fielding, co-founder of the Apache HTTP Server project, recognized these scalability issues. He proposed six architectural constraints that would fundamentally reshape how we build web systems:

  1. Client-Server: Separation of user interface concerns from data storage concerns
  2. Uniform Interface: Standardized communication methods across all services
  3. Layered System: Hierarchical architecture with clear boundaries
  4. Cache: Explicit labeling of responses as cacheable or non-cacheable
  5. Stateless: Each request contains all necessary information for processing
  6. Code on Demand: Optional ability to extend client functionality dynamically

These constraints became the foundation for HTTP 1.1. In 2000, Fielding documented this architectural style in his PhD dissertation, naming it REST (Representational State Transfer).

What Does REST Mean?

The acronym REST carries specific meaning:

Representational: Resources are represented in various formats (JSON, XML, HTML) depending on client needs. A single resource like a user profile can have different representations.

State: Refers to the current condition of a resource. For example, a shopping cart's state includes all items, quantities, and total price.

Transfer: The movement of resource representations between client and server using HTTP methods (GET, POST, PUT, DELETE, PATCH).

Designing Professional API Routes

URL Structure Anatomy

A well-structured API URL follows this pattern:

https://api.example.com/v1/organizations/123/projects?limit=10&page=1

Breaking this down:

  • Scheme: https://
  • Subdomain: api.example.com
  • Version: /v1
  • Resource Path: /organizations/123/projects
  • Query Parameters: ?limit=10&page=1

The Plural Noun Rule

Resource names in path segments should always be plural, even when fetching a single item:

✅ GET /organizations
✅ GET /organizations/123
✅ GET /books/456

❌ GET /organization/123
❌ GET /book/456

Path Readability Guidelines

When creating readable URLs:

  • Use lowercase letters
  • Replace spaces with hyphens for multi-word phrases
  • Avoid underscores
✅ /books/harry-potter-and-the-philosophers-stone
❌ /books/Harry Potter and the Philosophers Stone
❌ /books/harry_potter_and_the_philosophers_stone

Hierarchical Relationships

The forward slash (/) indicates hierarchical relationships between resources:

/organizations/{organizationId}/projects/{projectId}/tasks

This clearly shows that tasks belong to projects, which belong to organizations.

Understanding HTTP Methods and Idempotency

Idempotency is a crucial concept: an operation is idempotent if performing it multiple times produces the same result as performing it once.

HTTP Methods Overview

http Methods
http Methods
Figure 2: Common HTTP methods and their idempotency

Why These Matter

GET is idempotent because reading data multiple times doesn't change server state.

PUT is idempotent because sending the same complete replacement multiple times results in the same final state.

PATCH is idempotent when updating the same fields with the same values produces identical results.

DELETE is idempotent because after the first deletion, subsequent attempts fail but don't change server state further.

POST is non-idempotent because each request typically creates a new, distinct resource with a unique identifier.

Designing CRUD Operations

Let's design a complete API for an organization resource:

List All Organizations

GET /organizations
Response: 200 OK

{
  "data": [
    {
      "id": "123",
      "name": "Tech Corp",
      "createdAt": "2024-11-01T10:00:00Z"
    }
  ],
  "total": 50,
  "page": 1,
  "totalPages": 5
}

Create Organization

POST /organizations
Response: 201 Created

Request:
{
  "name": "New Organization",
  "description": "A new company"
}

Response:
{
  "id": "124",
  "name": "New Organization",
  "description": "A new company",
  "createdAt": "2024-11-18T14:30:00Z"
}

Get Single Organization

GET /organizations/123
Response: 200 OK

{
  "id": "123",
  "name": "Tech Corp",
  "description": "Technology company",
  "createdAt": "2024-11-01T10:00:00Z"
}

Update Organization

PATCH /organizations/123
Response: 200 OK

Request:
{
  "description": "Updated description"
}

Response:
{
  "id": "123",
  "name": "Tech Corp",
  "description": "Updated description",
  "createdAt": "2024-11-01T10:00:00Z",
  "updatedAt": "2024-11-18T14:35:00Z"
}

Delete Organization

DELETE /organizations/123
Response: 204 No Content

Status Codes: Choosing the Right One

Success Codes

  • 200 OK: Standard success for GET, PATCH, PUT, or custom actions
  • 201 Created: New resource created via POST
  • 204 No Content: Successful DELETE with no response body

Error Codes

  • 404 Not Found: Use when requesting a specific resource that doesn't exist
  • 400 Bad Request: Invalid request data or validation errors
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Authenticated but not authorized
  • 500 Internal Server Error: Unexpected server errors

Important Distinction

When a list API returns no results due to filters, return an empty array with 200, not 404:

✅ GET /organizations?status=archived
Response: 200 OK
{
  "data": [],
  "total": 0,
  "page": 1,
  "totalPages": 0
}

❌ Response: 404 Not Found

Custom Actions

Custom actions are operations that don't fit standard CRUD patterns. Examples include archiving, cloning, or sending notifications.

Design Pattern

POST /organizations/123/archive
POST /projects/456/clone
POST /users/789/send-notification

Route Structure

{server_address}/{resources}/{resource_id}/{action_name}

Status Codes for Actions

  • Return 200 for actions that modify existing resources
  • Return 201 if the action creates a new resource (like cloning)

Example: Archive Organization

POST /organizations/123/archive
Response: 200 OK

{
  "id": "123",
  "name": "Tech Corp",
  "status": "archived",
  "archivedAt": "2024-11-18T15:00:00Z"
}

Enhancing List APIs

Pagination

Implement pagination to handle large datasets efficiently:

GET /organizations?page=2&limit=20
Response: 200 OK

{
  "data": [...],
  "total": 150,
  "page": 2,
  "limit": 20,
  "totalPages": 8
}

Safe Defaults: If clients don't specify pagination parameters, default to page=1 and limit=10 or 20.

Sorting

Allow clients to sort results:

GET /organizations?sortBy=name&sortOrder=ascending
GET /organizations?sortBy=createdAt&sortOrder=descending

Safe Defaults: Sort by createdAt in descending order (newest first) when no sort parameters are provided.

Filtering

Enable filtering by resource properties:

GET /organizations?status=active
GET /projects?priority=high&status=in-progress

Multiple filters can be combined naturally through query parameters.

Best Practices for Professional APIs

1. Provide Interactive Documentation

Use tools like Swagger/OpenAPI to create interactive documentation where developers can test endpoints directly.

2. Maintain Consistency

Keep everything uniform across your API:

  • Naming conventions (use camelCase for JSON fields)
  • Response structures
  • Error formats
  • Status code usage

3. Implement Safe Defaults

Don't force clients to specify obvious parameters:

// If client doesn't specify pagination
const page = req.query.page || 1;
const limit = req.query.limit || 20;

// If client doesn't specify sort
const sortBy = req.query.sortBy || "createdAt";
const sortOrder = req.query.sortOrder || "descending";

4. Avoid Abbreviations

Use clear, readable names:

✅ description
✅ createdAt
✅ organizationName

❌ desc
❌ crtd_at
❌ org_nm

5. Design Before Coding

Create your API interface specification before writing implementation code. This ensures:

  • Consistency across endpoints
  • Proper resource modeling
  • Clear understanding of requirements
  • Better collaboration with frontend developers

Real-World Example: Project Management API

Let's design a complete API for a project management system with organizations, projects, and tasks:

# Organizations
GET    /organizations
POST   /organizations
GET    /organizations/{id}
PATCH  /organizations/{id}
DELETE /organizations/{id}
POST   /organizations/{id}/archive

# Projects (nested under organizations)
GET    /organizations/{orgId}/projects
POST   /organizations/{orgId}/projects
GET    /organizations/{orgId}/projects/{id}
PATCH  /organizations/{orgId}/projects/{id}
DELETE /organizations/{orgId}/projects/{id}
POST   /organizations/{orgId}/projects/{id}/clone

# Tasks (nested under projects)
GET    /organizations/{orgId}/projects/{projectId}/tasks
POST   /organizations/{orgId}/projects/{projectId}/tasks
GET    /organizations/{orgId}/projects/{projectId}/tasks/{id}
PATCH  /organizations/{orgId}/projects/{projectId}/tasks/{id}
DELETE /organizations/{orgId}/projects/{projectId}/tasks/{id}
POST   /organizations/{orgId}/projects/{projectId}/tasks/{id}/complete

This structure clearly shows hierarchical relationships and provides intuitive, predictable endpoints.

Conclusion

REST API design doesn't have to be confusing. By following these established standards and guidelines, you can create APIs that are:

  • Intuitive for developers to use
  • Consistent and predictable
  • Scalable and maintainable
  • Well-documented and professional

Remember these key principles:

  1. Use plural nouns for resource paths
  2. Apply HTTP methods correctly based on idempotency
  3. Choose appropriate status codes
  4. Implement pagination, sorting, and filtering for lists
  5. Design custom actions with clear naming
  6. Maintain consistency throughout your API
  7. Always design your interface before implementation

With these guidelines, you can focus on building great business logic instead of worrying about whether your API follows industry standards. Your API consumers will thank you for the clarity and consistency.

Further Resources

  • REST API specification and documentation
  • OpenAPI/Swagger for API documentation
  • HTTP 1.1 specification for deeper protocol understanding
  • Roy Fielding's dissertation on REST architecture

Happy API designing! 🚀