Documentation

HTTP Methods & Web API

Some information on HTTP methods and web API.

HTTP, Methods & Web API

TL;DR HTTP is the language of the web; its verbs (methods) are the grammar that lets your client and server understand each other. Pick the right verb, send the right headers, and your API sings. Ignore the rules, and gremlins appear. This article explains the why and how - from raw request bytes to practical visual-programming workflows in Divooka.

1. Diving Deeper

We talked about the basics of using and designing REST APIs. Now we zoom in on the nuts & bolts:

Developers learn which method (GET, POST, etc.) to reach for, and why.
Testers / QA see how to reproduce real-world traffic in a Postman/Insomnia-style node graph.
Non-dev teammates get an intuition for “safe” vs. “destructive” calls (so they stop asking, “Can’t we just use POST for everything?”).

2. HTTP Fundamentals (the 10-Minute Refresher)

2.1 What is HTTP?

A stateless, text-based request/response protocol riding on TCP (or QUIC for HTTP/3).
One connection → one request → one response (multiplexed in HTTP/2, but conceptually the same).

2.2 The Three-Part Sandwich

<Request / Status Line>
<Header 1: value>
<Header 2: value>
...
<BLANK LINE>
<Optional Body>

That blank line (\r\n\r\n) is the secret sauce: it tells everyone “headers are done; body begins.”

2.3 Understanding: Safety • Idempotence • Cacheability

When working with HTTP methods, it helps to know three key properties that affect how requests behave—especially when you’re building flows, retrying actions, or caching responses.

🔹 Safe methods

These methods are read-only - they don’t change anything on the server. You can call them as often as you like without risk.

Examples: GET, HEAD, OPTIONS
Usage: Safe methods are ideal for prefetching or checking data without side effects.

🔹 Idempotent methods

These methods may change things, but doing them multiple times has the same effect as doing them once.

Examples: GET, PUT, DELETE, HEAD, OPTIONS
Usage: Great for retries - if a network glitch causes your request to repeat, you won’t accidentally create or delete multiple things.

🔹 Cacheable methods

These are methods where the response can be safely stored (cached) by a browser or proxy server.

Examples: GET (most common), sometimes HEAD
Usage: Makes your app faster and lighter by avoiding repeated calls for the same data.

Quick Summary:

Property	What It Means	Common Methods
Safe	Doesn’t change data	`GET`, `HEAD`, `OPTIONS`
Idempotent	Same result no matter how many times it’s sent	`GET`, `PUT`, `DELETE`, `HEAD`, `OPTIONS`
Cacheable	Response can be stored for reuse	`GET` (default), `HEAD`

3. Raw HTTP Message Format (Plain-Text Examples)

Looking at the Raw Text helps us:

Real-world insight: All the nice “HTTP Request” nodes in Divooka ultimately translate into a stream of plain text (plus \r\n separators) sent over TCP.
Debugging power: When something goes wrong (e.g., a header typo or a missing blank line), reading the raw message helps you spot exactly what’s off.
Learning bridge: Seeing the raw text reinforces how “Request Line → Headers → Blank Line → Body” maps to what our visual tool is doing under the hood.

3.1 Anatomy of a Raw HTTP Request

Example: A simple GET request for a JSON resource

GET /api/users/123 HTTP/1.1
Host: api.example.com
Accept: application/json
User-Agent: Divooka/1.0
Authorization: Bearer <token>

Line-by-line breakdown: 1. GET /api/users/123 HTTP/1.1 * Request Line: <METHOD> <PATH> <HTTP-VERSION>. * Here, GET is asking for the user with ID 123. * HTTP/1.1 tells the server which version of the protocol we speak. 2. Host: api.example.com * Required in HTTP/1.1 so the server knows which virtual host you want—especially important if one server hosts multiple domains. 3. Accept: application/json * “I’d like JSON back, please.” If omitted, server usually defaults to HTML or its own default format. 4. User-Agent: MyVisualTool/1.0 * Identifies the client. Postman or Divooka would send something like PostmanRuntime/7.28.4 instead. 5. Authorization: Bearer <token> * Common way to send a JWT or OAuth 2.0 token. 6. (Blank line) * CRLF CRLF separator: Two consecutive \r\n sequences mark the end of headers. Without this, the server will keep waiting for more header lines! 7. (No body follows, because GET doesn’t usually send one.)

3.2 Anatomy of a Raw HTTP Response

Example: Server’s response to that GET

HTTP/1.1 200 OK
Date: Mon, 02 Jun 2025 14:35:22 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 111
Cache-Control: no-cache, no-store
ETag: "5f4dcc3b..."

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "created_at": "2025-05-20T08:15:00Z"
}

Notes Content-Length must equal 111 bytes (the exact JSON payload). If the server streams with chunked encoding, it omits Content-Length and sends size-prefixed chunks instead.

Line-by-line breakdown: 1. HTTP/1.1 200 OK * Status Line: <HTTP-VERSION> <STATUS_CODE> <REASON_PHRASE>. * Here, 200 OK means “Success, and here’s the payload.” 2. Date: Mon, 02 Jun 2025 14:35:22 GMT * The server’s clock. Handy if you need to compare timestamp headers or debug timeouts. 3. Content-Type: application/json; charset=utf-8 * Tells clients how to interpret the body. If your Divooka flow expected text/html, you’d know something’s off. 4. Content-Length:1117 * Exact byte length of the body that follows. Without this (or chunked encoding), clients won’t know where the body ends. 5. Cache-Control: no-cache, no-store * Instructs intermediaries (browsers, CDNs) not to cache this response. 6. ETag: "5f4dcc3b5aa765d61d8327deb882cf99" * An identifier for this specific version of the resource. Later, clients can send If-None-Match: "<etag>" in a GET to check if data changed. 7. (Blank line) * Signals “headers are done.” The next bytes belong to the body. 8. Body: Raw JSON payload, exactly 97 bytes long (including whitespace and line breaks).

{
"id": 123,
"name": "Alice",
"email": "[alice@example.com](mailto:alice@example.com)",
"created\_at": "2025-05-20T08:15:00Z"
}

3.4 Sending a Raw POST with a JSON Body

Below is a more elaborate example showing how a POST /contacts with a JSON payload looks in pure text. Notice the Content-Length header must match the byte count of the body (including braces, quotes, newlines).

POST /api/contacts HTTP/1.1
Host: api.example.com
User-Agent: MyVisualTool/1.0
Content-Type: application/json
Content-Length:  84
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

{
  "first_name": "Bob",
  "last_name": "Smith",
  "email": "bob.smith@example.com"
}

Header side: • First five lines are all headers or the request line. • After the blank line, everything is the body. • The server reads exactly 84 bytes after that blank line—no more, no less.
Body side: • JSON payload must be syntactically valid (commas, quotes, braces properly balanced). • If you accidentally typed Contnt-Length: 85, the server would wait for one extra byte or might reject your request.

3.5 How “Chunked” Transfer Encoding Looks

Some servers send large bodies in pieces (“chunks”) so they don’t need to know Content-Length up front. Chunked responses look like this:

HTTP/1.1 200 OK
Date: Mon, 02 Jun 2025 15:00:00 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked

1f      <– hex length of first chunk: 31 bytes
{"page":1,"per_page":10,"total":42}
2a      <– hex length of next chunk: 42 bytes
{"data":[{"id":1,...},{"id":2,...},...]}
0       <– “0” means “no more chunks”

How chunked works: 1. Server sends a hex number (e.g., 1f) followed by \r\n. That tells you “31 bytes coming next.” 2. Then the next 31 bytes of data (e.g., that small JSON object), followed by \r\n. 3. Then another hex number (2a = 42 bytes), etc. 4. A final 0\r\n\r\n signals “that’s all, thanks.”
Why chunked matters: • Your Divooka “HTTP Request” node usually hides this, but if you use a plain‐text “Raw Socket” node, you’ll see exactly these pieces fly by. • Chunked responses don’t include a Content-Length header. Instead, the client must reassemble chunks until it sees a zero‐length chunk.

3.6 Common Gotchas

Oops	Symptom	Fix
Forgetting the blank line	“400 Bad Request” instantly	Add `\r\n\r\n` after headers
Wrong `Content-Length`	Connection hangs or truncates	Let your client/tool calculate it
Mixed line endings (`\n` only)	Some servers reject	Always use `\r\n` in raw mode

4 CRUD Meets HTTP Methods

CRUD stands for:

Create: Adding a new record or resource (e.g., creating a user account).
Read: Retrieving or viewing existing data (e.g., fetching a user’s profile).
Update: Modifying existing data-either replacing it entirely or changing only certain fields.
- Whole update replaces the entire resource.
- Partial update changes only specified fields.
Delete: Removing a record or resource from the system.

CRUD	Typical Method	Why This Pairing Works
Create	POST	Non-idempotent; server chooses new URI
Read	GET (or HEAD)	Safe and cacheable
Update-whole	PUT	Idempotent full replacement
Update-partial	PATCH	Idempotent field-level change
Delete	DELETE	Idempotent removal

4.1 When CRUD Doesn’t Fit

Login/logout – POST /auth/login, POST /auth/logout
Complex actions – POST /payments/{id}/capture
Bulk operations – POST /users/bulk_delete with a JSON array of IDs

5 Method-by-Method Walkthrough

Every section below follows the same pattern:

Semantics • Idempotence / Safety • Typical Status Codes • Divooka Example • Common Pitfalls

5.1 GET

Safe + idempotent + cacheable
Status 200 OK, 304 Not Modified.
Divooka: Drag an Send (HTTP) Request node → Method = GET → URL = {{base}}/users?active=true → connect to Preview JSON.
Gotchas: Do not mutate data in a GET (“it’s just a harmless tracking pixel!” … until the ad blocker deletes half your DB).

5.2 POST

Create or process; not idempotent by default.
Status 201 Created (new URI in Location header) or 200 OK.
Divooka: Add a Text or (YAML) To JSON node, pick POST /users, body {"name": "Bob"}.
Pitfall: Double-submitting a payment form on slow Wi-Fi → two charges. Use Idempotency-Key headers or backend deduping.

5.3 PUT

Full replace of the resource at the given URI. Idempotent.
Status 200 OK (body), 204 No Content (empty).
Divooka: PUT /users/123 with the complete user object (as JSON).
Pitfall: Sending only changed fields-server overwrites missing ones with null.

5.4 PATCH

Partial update; idempotent if implemented sanely.
Body is either “merge patch” (just the changed fields) or RFC 6902 JSON Patch.
Divooka: Use the Text node for partial JSON → PATCH /users/123 with {"email": "new@x.com"}.
Pitfall: Clients & servers disagreeing on patch format → 415 Unsupported Media Type.

5.5 DELETE

Removes resource; idempotent.
Status 204 No Content (success), 404 Not Found (already gone).
Divooka: Send Request node with DELETE → feed status into Branch: if 204 show “gone”, else log error.
Pitfall: Unauthenticated deletes (whoops!).

5.6 HEAD

Like GET but headers-only.
Use to probe existence or get metadata (Content-Length, Last-Modified).
Divooka: HEAD /videos/intro.mp4 → if Content-Length > 10 MB, stream thumbnail instead.

5.7 OPTIONS

“What can I do here?” - returns Allow header & CORS rules.
Essential for browser preflights (Access-Control-Request-Method).
Divooka: OPTIONS /users → parse Allow, enable/disable buttons dynamically.
Pitfall: Server ignores OPTIONS → cross-origin JS cries.

5.8 Less-Seen Methods (TRACE, CONNECT, custom)

TRACE – echo request (debugging; often disabled).
CONNECT – tunnels (TLS over proxy).
Custom – e.g., WebDAV’s PROPFIND, REPORT. Divooka can send any token in the method field.

6. Status Codes & Their Friends

Code	Verb(s)	Meaning	Divooka Tip
200 OK	GET/PUT/PATCH	Success with body	View in JSON Viewer
201 Created	POST	Resource made; see `Location`	Extract header to variable
204 No Content	PUT/PATCH/DELETE	Success, no body	Skip JSON parsing
301/302	Any	Redirect, changes GET/POST rules	Auto-follow? Toggle in node
307/308	Any	Redirect, preserve method	Good for PUT → PUT
400	Any	Bad syntax/body	Show error toast
401/403	Any	Auth fail / forbidden	Refresh token logic
404	Any	Not found	Retry? Probably not
405	Any	Method not allowed	You picked wrong verb
500/503	Any	Server fault / overload	Add retry/backoff loop

7 Best Practices & Common Pitfalls

Choose the right verb – Proxies, caches, SDK generators all depend on it.
Set Content-Type and Accept – Autodetect is a myth.
Use idempotency keys on risky POSTs (payments, sign-ups).
Handle CORS – If browsers will call you, support OPTIONS.
Version your API politely – path (/v2/users) or header (Accept-Version), don’t overload methods mid-flight.
Secure destructive verbs – Require auth for PUT/PATCH/DELETE.
Parallelize safely – GETs may run concurrently; two PUTs racing on the same resource should be serialized or use ETags.

8 Advanced Topics (Optional Jump-Ahead)

HATEOAS – Responses include future actions (_links with method hints).
Conditional requests – If-None-Match, If-Match to save bandwidth & avoid lost updates.
HTTP/2 multiplexing – Many requests in one connection; methods unchanged.
GraphQL vs. REST – Everything is POST, but caching now relies on query hash.
Webhooks – They’re just POSTs in reverse; design receivers with the same verb discipline you expect from clients.

9 Putting It All Together: Sample End-to-End Scenarios

Below are three realistic workflows-each broken into clear steps-that show how different HTTP methods work together in a single flow. Think of each step as a node in Divooka: the method you pick drives what happens next. After these scenarios, there’s a quick look at how you might map one of them into a simple visual pipeline.

9.1 Scenario A: User Registration Flow

Imagine a new user signing up on your site. You need to prevent cross-site attacks, create the account, confirm their email, and finally let them update their profile. Here’s how it plays out:

Fetch a CSRF token (GET /csrf-token). First, your client sends a GET /csrf-token request. The server responds with a token in the body (for example, { "csrf_token": "abc123" }). In Divooka, that might be a GET node connected to a “store token” node that saves csrf_token into a variable.
Submit the registration form (POST /register). Next, the client does a POST /register with a JSON body like:
```
{
  "username": "jane_doe",
  "email": "jane@example.com",
  "password": "s3cur3",
  "csrf_token": "abc123"
}
```
If everything’s valid, the server returns status 201 (Created) and maybe a message saying “Please verify your email.” In Divooka, you’d use a POST node, include X-CSRF-Token or put it in the JSON, and then route the response to a “check status” node. If it’s 201, move on; if it’s 400, show an error.
Poll for email verification (GET /verify?token=…). After registration, the user clicks the link in their email (something like /verify?token=xyz). Your client can simulate polling by repeatedly sending GET /verify?token=xyz. Each time, the server might reply:
- 200 OK { "verified": false } until the user clicks the real link
- Then 200 OK { "verified": true } once they’ve clicked In Divooka, you could use a loop: a GET node checks response.body.verified; if false, wait a few seconds and retry (up to a limit); if true, proceed.
Update the new user’s profile (PATCH /users/). Once the account is verified, the client sends PATCH /users/123 (assuming the server gave back id = 123) with, for example:
```
{ "display_name": "Jane Doe", "avatar_url": "https://..." }
```
This partial update lets the user personalize their account. The server returns 200 OK and the updated user object. In Divooka, a PATCH node picks up the stored id and sends the JSON patch. If it succeeds, you show “Welcome, Jane!”-if not, an error handler kicks in.

9.2 Scenario B: Inventory Management

Suppose you run an e-commerce site and need to keep your warehouse in sync. You want to list all items, update stock levels, delete sold-out products, and add new ones in batch. Here’s a straightforward way:

Retrieve the current items (GET /items). The client sends GET /items, and the server returns a JSON array:
```
[
  { "id": 101, "name": "Widget A", "quantity": 5 },
  { "id": 102, "name": "Widget B", "quantity": 0 },
  { "id": 103, "name": "Widget C", "quantity": 12 }
]
```
In Divooka, a GET node feeds into a “For Each” node that iterates over each item in response.body.
Update quantities where needed (PUT /items/). For any item whose stock changed-for example, Widget A went from 5 to 3-you send:
```
PUT /items/101
{
  "id": 101,
  "name": "Widget A",
  "quantity": 3
}
```
Using Divooka, each loop iteration checks if quantity needs adjusting; if yes, it calls a PUT node with the full item object. The server replies 200 OK or 204 No Content upon success.
Delete sold-out items (DELETE /items/). If quantity is 0 (like Widget B), the client dispatches DELETE /items/102. The server responds 204 No Content meaning “Item gone.” In Divooka, the same For Each loop can contain a conditional: if quantity == 0, call the DELETE node; otherwise, skip it.
Bulk-add new items (POST /items/bulk). Finally, to add several new products at once, send one request:
```
POST /items/bulk
{
  "items": [
    { "name": "Widget D", "quantity": 20 },
    { "name": "Widget E", "quantity": 15 }
  ]
}
```
The server returns 201 Created with a list of new IDs:
```
{ "created": [ { "id": 104 }, { "id": 105 } ] }
```
In Divooka, that’s a single POST node with a JSON Builder that loops over your “newItems” list. After success, you might log a summary or show a “Bulk add complete” message.

9.3 Scenario C: Automated Error-Handling & Retry Logic

When services get busy, you don’t want your entire flow to crash. Instead, handle 503 Service Unavailable by retrying, then alert if it still fails. Here’s a simple pattern:

Initial request (GET /health-check). Start with a GET /health-check. The server normally returns 200 OK { "status": "healthy" }. In Divooka, route the response into a “Switch” node that checks statusCode.
If you see 503, pause and retry. If statusCode == 503, use a “Delay” node set to 5000 ms (5 seconds), then loop back to the same GET node. Keep a counter of retries-stop after 3 attempts. In Divooka, that might look like a small sub-flow with a variable retryCount that increments each time you hit 503.
If still failing after retries, send an alert (POST /alerts). When retryCount hits 3 and you’re still receiving 503, switch to a POST /alerts node, with body:
```
{
  "message": "Health check still failing after 3 retries.",
  "timestamp": "2025-06-02T15:00:00Z"
}
```
The server responds 201 Created. In Divooka, you can connect that to a “Notification” node to email or log the issue.
If any GET succeeds (200), continue your normal flow. As soon as you see 200 OK from GET /health-check, you break out of retries and proceed with other tasks (e.g., a scheduled data fetch or a critical update). In Divooka, that’s just another branch out of the Switch node for statusCode == 200.

9.4 Sample Pipeline Diagram (Procedural Context)

Below is a rough sketch of how Scenario B might look in Divooka. Each box represents a node, and arrows show data flow. The method (GET/PUT/DELETE/POST) in each node drives whether you’re fetching, updating, removing, or creating.

[Start]
   ↓
[GET /items]            ← Fetch list of items
   ↓
┌───────────────┐
│For Each item │────────────────────────────────────────────────────╮
└───────────────┘                                                │
   ↓                                                            │
[Check quantity]                                                │
   ↓                                                            │
[quantity > 0?] ─ No─▶[DELETE /items/{id}] ──→(Log “Deleted”)   │
   ↓ Yes                                                        │
[quantity changed?] ─ No─▶(Skip update)                         │
   ↓ Yes                                                        │
[PUT /items/{id}] ──→(Log “Updated”)                            │
   ↓                                                            │
   ⤵─────────────────────────────────────────────────────────────────┘
   ↓
[Collect results]
   ↓
[POST /items/bulk]   ← Add new items
   ↓
[Show “Done” Message]
   ↓
[End]

GET /items node retrieves all items.
The response loops through each item (For Each item).
A Decision node checks if quantity == 0.
- If yes, call DELETE /items/ and log success.
- If no, check if quantity has changed.
  - If changed, call PUT /items/ to update and log.
  - Otherwise, do nothing and move on.
After finishing the loop, the pipeline collects any new items you want to add and sends a POST /items/bulk with that batch.
Finally, a node displays “Done” or writes to a log.

Practical Notes

You see how each HTTP method fits its role - DELETE only when quantity == 0, PUT only when a change is needed, POST only for batch creation.
Divooka’s visual model makes these branches and loops intuitive: you drag-n-drop to add a decision node, choose your variables (like quantity), and wire it up.
By combining Switch, Delay, and retry counters from Scenario C, you can handle errors gracefully: retry a few times, then alert.

Use these examples as templates. Swap in your own endpoints, adjust headers, and let Divooka do the heavy lifting of inserting the correct blank lines, computing Content-Length, and routing success vs. failure paths. When you need to debug, step into the program flow and see intermediate results or use low level nodes and paste in the exact HTTP text to watch how headers and bodies fly over the wire.

10 Cheat-Sheet Reference

Method	Safe	Idempotent	Success Codes	Typical Use
GET	✔	✔	200, 304	Read data
HEAD	✔	✔	200	Read headers
POST	✘	✘	201, 200	Create / action
PUT	✘	✔	200, 204	Replace resource
PATCH	✘	✔	200, 204	Partial update
DELETE	✘	✔	204, 200	Remove resource
OPTIONS	✔	✔	200	Discover / CORS

11 Key Takeaways

HTTP is just text over the wire-master the raw format and you can debug anything.
Method choice influences caching, retries, security, and even billing when you’re on a per-request plan.
Divooka (or any other tool) automates headers, blank lines, and Content-Length, but knowing what’s underneath turns you from user into wizard.
When in doubt: GET to read, POST to create, PUT/PATCH to update, DELETE to remove. If you break that rule, have a documented reason.

Next Steps

Fire up Divooka, create a new workspace document called “Method Playground”
Rebuild the examples above - toggle raw mode to watch the bytes.
Try adding an Idempotency-Key header on a POST, then hit “Run” five times. Note what your server does.
Bookmark this article. Your future self (staring at a mysterious 405) will thank you.

References

Knowledge Base on REST API.
Divooka Web API Testing example.