REST Basics and HTTP Methods: The Language of Web APIs

What REST Actually Means

In 2000, Roy Fielding published his doctoral dissertation describing REST - Representational State Transfer. At the time, the dominant approach to web APIs was SOAP: verbose XML documents, complex schemas, and WSDLs that made every API feel like filing taxes. REST was revolutionary because it said: the web already has a perfect architecture for APIs. Just use it.

In practice, REST means: use URLs to identify things (resources), and use HTTP methods to describe what you want to do with those things. Think of it like a library. Each book has a unique location (URL). The actions you can perform are standard: read it, add a new one, update it, or remove it. REST is this simple pattern applied to web APIs.

HTTP Methods: The Verbs

HTTP gives us standard methods (verbs) for different operations:

Method   Action      Idempotent?  Safe?   Request Body?
-------  ----------  -----------  ------  -------------
GET      Read        Yes          Yes     No
POST     Create      No           No      Yes
PUT      Replace     Yes          No      Yes
PATCH    Update      No*          No      Yes
DELETE   Remove      Yes          No      No
HEAD     Headers     Yes          Yes     No
OPTIONS  Discover    Yes          Yes     No

* PATCH can be idempotent if designed carefully

The distinction between safe and idempotent matters: safe means no side effects at all (GET never changes data). Idempotent means calling it multiple times has the same effect as calling it once (DELETE /users/42 deletes the user whether you call it once or five times).

A Complete REST API Example

Here is what a well-designed REST API for a bookstore looks like in practice:

# List all books (paginated)
GET /v1/books?genre=fiction&limit=20&cursor=abc123
Response: 200 OK
{
  "data": [{"id": 1, "title": "Dune", "author": "Herbert"}...],
  "pagination": {"next_cursor": "def456", "has_more": true}
}

# Get a single book
GET /v1/books/42
Response: 200 OK
{"id": 42, "title": "Neuromancer", "author": "Gibson", "isbn": "978-0441569595"}

# Create a book
POST /v1/books
Body: {"title": "Snow Crash", "author": "Stephenson", "isbn": "978-0553380958"}
Response: 201 Created
Location: /v1/books/43

# Update a book's price
PATCH /v1/books/42
Body: {"price": 14.99}
Response: 200 OK

# Delete a book
DELETE /v1/books/42
Response: 204 No Content

URLs as Resource Identifiers

Good REST URLs describe WHAT you are operating on, not WHAT you are doing:

• Good: GET /users/42/orders - get orders for user 42
• Good: POST /orders - create a new order
• Bad: POST /getOrders - this puts the action in the URL (that is the method's job)
• Bad: POST /createUser - again, POST already means 'create'

Status Codes: The Server's Response Language

HTTP status codes tell the client what happened. Using the right code means every HTTP client, proxy, and monitoring tool automatically understands the outcome:

• 200 OK - everything worked, here is your data
• 201 Created - new resource created successfully (always include a Location header)
• 204 No Content - success, but nothing to return (common for DELETE)
• 400 Bad Request - the client sent invalid data
• 401 Unauthorized - you are not logged in (misleading name: it really means 'unauthenticated')
• 403 Forbidden - you are logged in but do not have permission
• 404 Not Found - that resource does not exist
• 409 Conflict - the operation conflicts with current state (like creating a user with an existing email)
• 429 Too Many Requests - rate limited, slow down
• 500 Internal Server Error - something broke on the server side

REST Constraints That Matter

For a system to be truly RESTful, it should follow these principles:

1. Stateless - each request contains all information needed to process it. The server does not 'remember' previous requests.
2. Uniform interface - consistent URL patterns and HTTP method usage across your entire API.
3. Resource-based - everything is a noun (resource), operations are expressed through HTTP methods.
4. Cacheable - responses should indicate whether they can be cached and for how long.

Why Statelessness Matters for Scale

The stateless constraint is the most important for system design. If a server does not store session state, any server can handle any request. This means you can put a load balancer in front of 100 servers and route requests to any of them. Scaling becomes adding more servers.

Compare this to a stateful design where the server remembers your shopping cart in memory. Now you must route all of that user's requests to the same server (sticky sessions), which makes scaling much harder and creates a single point of failure.

REST vs the Alternatives

Style      Best For                   Trade-off
---------- -------------------------- ------------------------------
REST       CRUD apps, public APIs,    Simple but verbose for complex
           browser-friendly services   queries and nested data

GraphQL    Complex frontends with     Flexible but complex caching,
           varied data needs          harder to rate-limit

gRPC       Internal microservices,    Fast but not browser-friendly,
           high-performance systems   requires code generation

REST is the default choice for public APIs because every programming language and tool speaks HTTP natively. Start with REST unless you have a specific reason to choose something else.

Interview Tip

When designing an API in an interview, start by listing your resources (nouns). Draw a table: Resource | methods | URL. Then mention: 'I would make this API stateless so any server behind the load balancer can handle any request. Tokens carry authentication state, not the server.' This shows you connect API design to scalability.

Key Takeaway

REST is about using HTTP as it was designed: URLs identify resources, methods describe actions, status codes communicate outcomes. The stateless constraint is what makes REST APIs infinitely scalable. It remains the default choice for web APIs because of its simplicity and universal tooling support.