REST API best practices in HLD - Deep Dive

Overview - REST API best practices

What is it?

A REST API is a way for different software systems to talk to each other over the internet using simple rules. It uses standard web methods like GET, POST, PUT, and DELETE to perform actions on data. REST APIs organize data into resources, each identified by a URL. They are designed to be easy to use, scalable, and flexible for many applications.

Why it matters

REST APIs let different programs work together smoothly, like apps talking to servers or services sharing data. Without good REST API practices, systems become hard to maintain, slow, or confusing to use. This can cause delays, errors, and unhappy users. Following best practices ensures APIs are reliable, secure, and easy to grow as needs change.

Where it fits

Before learning REST API best practices, you should understand basic web concepts like HTTP methods, URLs, and client-server communication. After this, you can explore advanced topics like API security, versioning, and performance optimization. REST API design is a key step in building scalable web services and microservices architectures.

Mental Model

Core Idea

A REST API is like a well-organized library where each book (resource) has a clear address (URL) and you use simple commands (HTTP methods) to read, add, update, or remove books.

Think of it like...

Imagine a restaurant menu where each dish is a resource you can order, change, or remove by telling the waiter exactly what you want using simple words like 'get me', 'add', 'change', or 'remove'.

┌─────────────┐       ┌───────────────┐       ┌─────────────┐
│   Client    │──────▶│   REST API    │──────▶│   Database  │
└─────────────┘       └───────────────┘       └─────────────┘

Client sends HTTP requests (GET, POST, PUT, DELETE) to REST API.
REST API processes requests and interacts with Database resources.
Responses return data or status back to Client.

Build-Up - 7 Steps

1

Foundation

Understanding REST and HTTP Basics

Concept: Learn what REST means and how HTTP methods work to manipulate resources.

REST stands for Representational State Transfer. It uses HTTP methods like GET (read), POST (create), PUT (update), and DELETE (remove) to work with resources identified by URLs. Each resource is a piece of data or service you want to access or change.

Result

You can identify how to perform basic operations on data using standard HTTP methods.

Understanding REST and HTTP basics is essential because all REST API actions rely on these simple, universal commands.

2

Foundation

Resource Identification with URLs

Concept: Learn how to name and organize resources clearly using URLs.

Each resource should have a unique URL that clearly shows what it represents. For example, /users/123 refers to user with ID 123. Use nouns for resources, not verbs. Avoid complex query strings for main resources.

Result

You can design clear, predictable URLs that make APIs easy to understand and use.

Clear resource naming helps clients guess URLs and reduces confusion, making APIs more user-friendly.

3

Intermediate

Using HTTP Methods Correctly

🤔Before reading on: do you think POST should be used to update data or only to create new data? Commit to your answer.

Concept: Learn the proper use of HTTP methods to match their intended actions.

GET retrieves data without changing it. POST creates new resources. PUT updates or replaces existing resources. PATCH partially updates resources. DELETE removes resources. Using methods correctly ensures predictable API behavior.

Result

Your API clients will know exactly what each request does, avoiding accidental data loss or confusion.

Knowing the correct use of HTTP methods prevents bugs and security issues caused by misuse of API actions.

4

Intermediate

Statelessness and Idempotency

🤔Before reading on: do you think REST APIs should remember previous requests or treat each request independently? Commit to your answer.

Concept: Understand that REST APIs should not keep client state between requests and that some methods can be safely repeated.

REST APIs are stateless, meaning each request contains all information needed. Idempotent methods like GET, PUT, and DELETE can be called multiple times without changing the result beyond the first call. POST is not idempotent.

Result

APIs become easier to scale and more reliable because servers do not rely on past interactions.

Statelessness and idempotency simplify server design and improve fault tolerance in distributed systems.

5

Intermediate

Consistent Response Structure and Status Codes

🤔Before reading on: do you think APIs should always return the same format for success and error responses? Commit to your answer.

Concept: Learn to use standard HTTP status codes and consistent response formats for clarity.

Use status codes like 200 for success, 201 for created, 400 for bad request, 404 for not found, and 500 for server errors. Responses should have a consistent structure, including helpful messages and data fields.

Result

Clients can easily handle responses and errors without guessing what happened.

Consistent responses reduce client-side bugs and improve developer experience.

6

Advanced

Versioning and Backward Compatibility

🤔Before reading on: do you think changing an API without versioning breaks existing clients? Commit to your answer.

Concept: Learn how to manage API changes without disrupting users.

Use versioning in URLs (e.g., /v1/users) or headers to introduce changes. Maintain backward compatibility by supporting old versions or using feature flags. Communicate deprecation clearly.

Result

APIs evolve safely without breaking existing applications.

Proper versioning protects users and allows continuous improvement of APIs.

7

Expert

Security and Rate Limiting Best Practices

🤔Before reading on: do you think all REST APIs should allow unlimited requests from any client? Commit to your answer.

Concept: Understand how to protect APIs from misuse and attacks.

Use authentication (like OAuth or API keys) to verify clients. Use HTTPS to encrypt data. Implement rate limiting to prevent abuse and denial-of-service attacks. Validate inputs to avoid injection attacks.

Result

APIs remain secure, reliable, and performant under heavy or malicious use.

Security and rate limiting are critical to protect data and maintain service availability in real-world environments.

Under the Hood

REST APIs work by receiving HTTP requests from clients, parsing the request method and URL to identify the resource and action, then interacting with backend systems like databases or services to fulfill the request. The server then sends back an HTTP response with status codes and data. Statelessness means each request is independent, so the server does not store client session data between calls.

Why designed this way?

REST was designed to leverage the existing web infrastructure and HTTP standards to create simple, scalable, and flexible APIs. Statelessness allows easy scaling by avoiding server-side session storage. Using standard HTTP methods and status codes makes APIs predictable and interoperable. Alternatives like SOAP were more complex and less web-friendly, so REST became popular for modern web services.

┌───────────────┐        ┌───────────────┐        ┌───────────────┐
│   HTTP Client │───────▶│ REST API Server│───────▶│ Backend System│
│ (Browser/App) │        │ (Handles URLs, │        │ (Database,    │
│               │        │  Methods, etc) │        │  Services)    │
└───────────────┘        └───────────────┘        └───────────────┘

Each request is independent; server does not keep client state.
Server uses HTTP methods and status codes to communicate results.

Myth Busters - 4 Common Misconceptions

Quick: Do you think POST requests are idempotent and safe to repeat without side effects? Commit to yes or no.

Common Belief: POST requests can be safely repeated multiple times without changing the result.

Reality: POST is not idempotent; repeating a POST can create multiple resources or side effects.

Why it matters: Misusing POST can cause duplicate data or unintended actions, leading to data corruption or user confusion.

Quick: Do you think REST APIs must always use JSON for data exchange? Commit to yes or no.

Common Belief: REST APIs must use JSON format exclusively for requests and responses.

Reality: REST APIs can use any format like XML, YAML, or plain text; JSON is common but not mandatory.

Why it matters: Assuming JSON only limits flexibility and integration with systems that prefer other formats.

Quick: Do you think REST APIs should maintain client session state on the server? Commit to yes or no.

Common Belief: REST APIs keep track of client sessions to manage state between requests.

Reality: REST APIs are stateless; each request must contain all information needed to process it.

Why it matters: Stateful APIs are harder to scale and can cause unexpected errors when servers restart or requests route differently.

Quick: Do you think using verbs in URLs is a good REST practice? Commit to yes or no.

Common Belief: Including verbs like /getUser or /createOrder in URLs is recommended for clarity.

Reality: REST best practice is to use nouns for resources and HTTP methods for actions, not verbs in URLs.

Why it matters: Using verbs in URLs breaks uniformity and makes APIs less intuitive and harder to maintain.

Expert Zone

1

Idempotency is not just about safety but also about enabling retries and fault tolerance in distributed systems.

2

Choosing between PUT and PATCH depends on whether you want to replace the entire resource or update parts, impacting client and server complexity.

3

Versioning strategies affect long-term maintenance; URI versioning is simple but header-based versioning can be more flexible and less disruptive.

When NOT to use

REST APIs are not ideal when you need real-time bidirectional communication; in such cases, WebSockets or gRPC may be better. Also, for complex transactions requiring multiple steps, GraphQL or RPC might be more suitable.

Production Patterns

In production, REST APIs often use layered architecture with API gateways for routing, caching, and security. They implement pagination for large data sets, use HATEOAS for discoverability, and apply OAuth2 for secure access control.

Connections

HTTP Protocol

REST APIs build directly on HTTP methods and status codes.

Understanding HTTP deeply helps design better REST APIs that use the web's native features effectively.

Microservices Architecture

REST APIs are commonly used as communication interfaces between microservices.

Knowing REST API best practices is essential to build scalable and maintainable microservices.

Library Cataloging Systems

Both organize items (books/resources) with clear identifiers and standardized access methods.

Seeing REST APIs as catalog systems helps grasp resource naming and access consistency.

Common Pitfalls

#1 Using verbs in URLs instead of HTTP methods.

Wrong approach:

GET /getUser/123
POST /createOrder

Correct approach:

GET /users/123
POST /orders

Root cause:

Misunderstanding that HTTP methods already express actions, so verbs in URLs are redundant and confusing.

#2 Ignoring status codes and always returning 200 OK.

Wrong approach:

HTTP/1.1 200 OK
{"error": "User not found"}

Correct approach:

HTTP/1.1 404 Not Found
{"message": "User not found"}

Root cause:

Not using proper HTTP status codes leads to clients misinterpreting responses and handling errors poorly.

#3 Keeping server-side session state in REST APIs.

Wrong approach:

Server stores user login state between requests.

Correct approach:

Each request includes authentication tokens; server treats requests independently.

Root cause:

Confusing REST statelessness with traditional session-based web apps causes scalability and reliability issues.

Key Takeaways

REST APIs use standard HTTP methods and URLs to manipulate resources in a simple, predictable way.

Statelessness and idempotency are core principles that make REST APIs scalable and reliable.

Clear resource naming, consistent responses, and proper use of status codes improve API usability and client experience.

Versioning and security practices are essential to maintain and protect APIs as they evolve and scale.

Avoid common mistakes like verbs in URLs, ignoring status codes, and maintaining server state to build robust REST APIs.