REST API Complete Guide: HTTP Methods, Status Codes, Headers & Best Practices

REST (Representational State Transfer) APIs are the backbone of modern web development. Whether you are building a mobile app, a React frontend, or a microservices architecture, you will interact with REST APIs every day. This guide covers everything you need to know — from HTTP methods and status codes to authentication and best practices.

What is a REST API?

A REST API is an interface that follows a set of architectural constraints defined by Roy Fielding in his 2000 doctoral dissertation. The key principles of REST are:

Stateless — Each request contains all the information needed to process it. The server does not store client state between requests.
Client-Server — The client and server are separate. The client handles the UI, the server handles data storage and business logic.
Uniform Interface — Resources are identified by URLs. HTTP methods define actions on those resources.
Cacheable — Responses should indicate whether they can be cached to improve performance.
Layered System — Clients do not need to know if they are talking to the actual server or an intermediary (load balancer, cache, gateway).

HTTP Methods Explained

REST APIs use HTTP methods (also called verbs) to indicate the action to be performed on a resource:

GET — Retrieve Data

GET /api/users          — Get all users
GET /api/users/42       — Get user with ID 42
GET /api/users?city=Bengaluru  — Get users filtered by city

GET requests should be safe (no side effects) and idempotent (calling it multiple times gives the same result). Never use GET to modify data.

POST — Create a New Resource

POST /api/users
Content-Type: application/json

{
  "name": "Arjun Sharma",
  "email": "arjun@example.com",
  "role": "developer"
}

POST creates a new resource. The server assigns the resource ID. The response typically returns the newly created resource with its ID and a 201 Created status.

PUT — Replace an Existing Resource

PUT /api/users/42
Content-Type: application/json

{
  "name": "Arjun Kumar Sharma",
  "email": "arjun@example.com",
  "role": "senior-developer"
}

PUT replaces the entire resource. If you omit a field, it gets removed. PUT should be idempotent — calling it multiple times with the same data should produce the same result.

PATCH — Partially Update a Resource

PATCH /api/users/42
Content-Type: application/json

{
  "role": "tech-lead"
}

PATCH applies a partial update — only the fields you send are changed. Unlike PUT, omitted fields are left unchanged. Use PATCH when you only want to update specific fields.

DELETE — Remove a Resource

DELETE /api/users/42

DELETE removes the specified resource. A successful deletion typically returns 204 No Content (deleted, no response body) or 200 OK with a confirmation message.

HTTP Status Codes

Status codes tell the client what happened with their request. They are grouped into five categories:

2xx — Success

200 OK — Request succeeded. Used for GET, PUT, PATCH responses.
201 Created — Resource was created successfully. Used for POST responses.
204 No Content — Request succeeded but there is nothing to return. Used for DELETE.

3xx — Redirection

301 Moved Permanently — Resource has moved to a new URL permanently.
304 Not Modified — Cached version is still valid (used with ETags).

4xx — Client Errors

400 Bad Request — Request is malformed or missing required data.
401 Unauthorized — Authentication is required but missing or invalid.
403 Forbidden — Authenticated but not authorized to access this resource.
404 Not Found — Resource does not exist.
409 Conflict — Conflict with current state (e.g., duplicate email).
422 Unprocessable Entity — Validation failed (request is well-formed but invalid).
429 Too Many Requests — Rate limit exceeded.

5xx — Server Errors

500 Internal Server Error — Generic server error.
502 Bad Gateway — Server received an invalid response from an upstream server.
503 Service Unavailable — Server is temporarily down (maintenance or overload).

Important Request Headers

Content-Type: application/json      — Body format being sent
Accept: application/json            — Response format expected
Authorization: Bearer <token>       — Authentication token
X-API-Key: your-api-key             — API key authentication
Cache-Control: no-cache             — Do not use cached response
X-Request-ID: req-uuid-12345        — Unique request identifier for tracing

API Authentication Methods

REST APIs use several authentication mechanisms:

1. API Keys

Simple string tokens passed in a header or query parameter. Easy to implement but less secure if not protected.

GET /api/data?api_key=your-key-here
// or in header:
X-API-Key: your-key-here

2. Bearer Token (JWT)

The most common modern approach. Send a JWT in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

3. Basic Authentication

Username and password encoded in Base64. Only use over HTTPS:

Authorization: Basic dXNlcjpwYXNzd29yZA==

4. OAuth 2.0

Industry standard for delegated authorization. Used by Google, GitHub, and most major platforms. Involves access tokens and refresh tokens with defined scopes.

REST API Design Best Practices

Use nouns, not verbs in URLs — /api/users not /api/getUsers
Use plural nouns — /api/users not /api/user
Use HTTP methods to define actions — DELETE /api/users/42 not POST /api/deleteUser
Version your API — /api/v1/users — allows you to change the API without breaking existing clients
Return consistent error responses — always include an error code, human-readable message, and optional details
Use pagination for large datasets — /api/users?page=2&limit=20
Use HTTPS always — never serve an API over plain HTTP in production
Implement rate limiting — protect your API from abuse and return 429 Too Many Requests when exceeded

Testing REST APIs

Use our free HTTP Request Builder to test any REST API directly from your browser — no installation needed. You can also import cURL commands generated from API documentation and send them instantly.

Summary

REST APIs follow a simple, consistent pattern: URLs identify resources, HTTP methods define actions, and status codes communicate results. Understanding these fundamentals makes you a far more effective developer, whether you are building APIs or consuming them.

REST API Complete Guide: HTTP Methods, Status Codes and Best Practices