HTTP Methods: GET, POST & More

---

HTTP methods (also called verbs) tell the server what kind of operation you want to perform on a resource. Choosing the right method makes your API predictable, maintainable, and aligned with REST conventions.

---

---

---

1. The Complete Set of HTTP Methods

---

---

Key Properties Explained

---

• Safe: Does not alter server state. A safe method should only read data, never write it.
• Idempotent: Calling the same operation multiple times produces the same result as calling it once. DELETE /users/42 twice — the user is still gone after both calls.
• Cacheable: The response can be stored and reused for future equivalent requests.

---

---

---

2. GET — Retrieving Data

---

GET is the most common HTTP method. Every time you visit a web page, your browser sends a GET request.

---

Rules for GET

• Never change server state — GET must be a pure read
• No request body (browsers ignore it; some servers reject it)
• Always cacheable — browsers and CDNs can store GET responses
• Query parameters go in the URL: /users?sort=name&page=2

---

// Simple GET
const response = await fetch('/api/courses');
const courses  = await response.json();

---

// GET with query parameters const params = new URLSearchParams({ level: 'beginner', sort: 'title', page: '1' }); const response = await fetch(/api/courses?${params}); const courses = await response.json();

---

// GET a specific resource by ID const response = await fetch('/api/courses/42'); const course = await response.json();

---

Raw GET request:

GET /api/courses?level=beginner&page=1 HTTP/1.1
Host: api.nandhoo.com
Accept: application/json
Authorization: Bearer eyJhbG...

---

Expected response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: public, max-age=60

---

[{ "id": 1, "title": "HTML5", ... }, ...]

---

---

---

3. POST — Creating Resources

---

POST sends data to the server to create a new resource or trigger an action (like sending an email, running a batch job, or logging in).

---

Rules for POST

• Has a request body with the data to create
• The server decides the new resource's URL (usually returned in the Location header)
• Not idempotent — clicking "submit" twice may create two records
• Response is usually 201 Created with the new resource in the body

---

// Create a new user account
const response = await fetch('/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'AliceCodes',
    email:    'alice@example.com',
    password: 'secure-hashed-server-side'
  })
});

---

// 201 Created response includes the new resource const newUser = await response.json(); console.log('Created:', newUser.id); console.log('Find at:', response.headers.get('Location')); // /api/users/99

---

Raw POST request:

POST /api/users HTTP/1.1
Host: api.nandhoo.com
Content-Type: application/json
Content-Length: 68

---

{"username":"AliceCodes","email":"alice@example.com"}

---

Expected response:

HTTP/1.1 201 Created
Location: /api/users/99
Content-Type: application/json

---

{"id":99,"username":"AliceCodes","createdAt":"2025-03-31T07:38:00Z"}

---

---

---

4. PUT — Replacing a Resource Completely

---

PUT replaces the entire resource at a given URL with the data in the request body. Fields not included in the body are deleted or reset to defaults.

---

// Replace the entire user profile
const response = await fetch('/api/users/99', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'AliceCodes',
    email:    'alice-new@example.com',
    level:    'intermediate',
    bio:      'I love coding!'
    // ⚠️ All fields must be provided — omitted fields will be cleared
  })
});

---

If idempotent — sending the same PUT twice results in the same server state.

---

---

---

5. PATCH — Partial Updates

---

PATCH updates only the specified fields of a resource, leaving everything else unchanged.

---

// Only update the email — everything else stays the same
const response = await fetch('/api/users/99', {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'alice-patched@example.com'
    // username, level, bio are untouched
  })
});

---

PUT vs PATCH — When to Use Which

---

---

---

---

6. DELETE — Removing a Resource

---

DELETE removes the resource at the given URL.

---

// Delete a course by ID
const response = await fetch('/api/courses/42', {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${token}` }
});

---

if (response.status === 204) { console.log('Deleted successfully'); } else if (response.status === 404) { console.log('Course not found — already deleted?'); }

---

• Response is usually 204 No Content (success, no body)
• Or 200 OK with a confirmation body
• Idempotent — deleting something that's already gone returns the same state (though status might be 404)

---

---

---

7. HEAD — Check Before You Download

---

HEAD is identical to GET, but the server returns only the headers — no body. Use it to:

---

• Check if a resource exists (without downloading it)
• Get the file size (Content-Length) before downloading
• Check if cached content is still fresh (ETag, Last-Modified)

---

// Check if a large file has changed before downloading it
const headRes = await fetch('/downloads/course-data.zip', {
  method: 'HEAD'
});

---

const size = headRes.headers.get('content-length'); const etag = headRes.headers.get('etag'); const changed = etag !== localStorage.getItem('last-etag');

---

console.log(File size: ${(size / 1024 / 1024).toFixed(1)} MB); console.log(Changed since last download: ${changed});

---

if (changed) { // Now download the full file const fullRes = await fetch('/downloads/course-data.zip'); const blob = await fullRes.blob(); localStorage.setItem('last-etag', etag); }

---

---

---

8. OPTIONS — CORS Preflight

---

OPTIONS is used automatically by browsers before certain cross-origin requests (CORS preflight). You rarely call it manually.

---

// Browser sends this automatically before a cross-origin PUT/DELETE/custom-header request
OPTIONS /api/users/99 HTTP/1.1
Host: api.otherdomain.com
Origin: https://nandhoo.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: Authorization, Content-Type

---

Server must respond with:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://nandhoo.com
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Max-Age: 86400

---

---

---

9. REST API Design with HTTP Methods

---

A well-designed REST API uses HTTP methods consistently:

---

Resource: /api/courses

---

GET /api/courses → List all courses POST /api/courses → Create a new course

---

GET /api/courses/:id → Get a specific course PUT /api/courses/:id → Replace a course entirely PATCH /api/courses/:id → Update part of a course DELETE /api/courses/:id → Delete a course HEAD /api/courses/:id → Check if a course exists

---

Nested resources: GET /api/courses/:id/chapters → List all chapters for a course POST /api/courses/:id/chapters → Add a chapter to a course DELETE /api/courses/:id/chapters/:cid → Remove a specific chapter

---

Method → Status Code Conventions

---

---

---

---

10. Common Mistakes

---

---

---

---

11. Seeing All Methods In Practice

---

const API = 'https://api.nandhoo.com';
const headers = { 
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${token}`
};

---

// 1. GET — fetch all courses const list = await fetch(${API}/courses, { headers }).then(r => r.json());

---

// 2. POST — create a course const created = await fetch(${API}/courses, { method: 'POST', headers, body: JSON.stringify({ title: 'HTTP Basics', level: 'beginner' }) }).then(r => r.json());

---

// 3. PUT — fully replace the course await fetch(${API}/courses/${created.id}, { method: 'PUT', headers, body: JSON.stringify({ title: 'HTTP Deep Dive', level: 'intermediate', chapters: 10 }) });

---

// 4. PATCH — only update the title await fetch(${API}/courses/${created.id}, { method: 'PATCH', headers, body: JSON.stringify({ title: 'HTTP Mastery' }) });

---

// 5. DELETE — remove the course await fetch(${API}/courses/${created.id}, { method: 'DELETE', headers });

---

---

---

12. Review Questions

---

1. What is the difference between a safe and an idempotent method?
2. Why should GET requests never have side effects?
3. What is the key difference between PUT and PATCH?
4. What status code should a successful POST return, and what extra header should it include?
5. When would you use HEAD instead of GET?
6. What happens if you send a DELETE request to a URL that no longer exists?
7. Why is POST not idempotent?

---

---

---