REST API Guide

HTTP methods

Common status codes

Conditional requests and concurrency

• When multiple clients can edit the same row, one update can overwrite another unless the API checks a validator.
• ETag is a common validator. Clients can send `If-None-Match` for cache validation and conditional operations.
• This helps prevent mid-air collisions and avoids serving stale content when the resource changed.

Pragmatic CRUD mapping

• `GET /items` lists resources and `GET /items/{id}` reads one resource.
• `POST /items` creates a resource, while `PATCH /items/{id}` updates only the fields you send.
• `PUT /items/{id}` is best for full replacement and `DELETE /items/{id}` is idempotent by design.

Authentication patterns

• Use API keys for simple server-to-server access when the use case is narrow and low-risk.
• JWT bearer tokens are common for signed claims, but they must be protected in storage and transport.
• Use OAuth2 when third-party or delegated access is required, especially with scopes and refresh flows.
• PKCE matters for public clients such as mobile apps and SPAs because it protects the authorization code flow.
• Never place sensitive tokens in public client-side code unless the token is designed for public use.
• Return `401` for missing or invalid auth and `403` when the user is authenticated but not allowed.

Pagination and filters

• Support `page` and `limit` or cursor-based navigation so large tables do not overload the response.
• Add filters such as `status=active`, `country=IN`, or `search=video` to reduce noisy payloads.
• Return total count or next cursor so the client can keep loading cleanly.
• Keep sorting deterministic so new inserts do not break paging unexpectedly.

Rate limiting, retries, and idempotency

• Return `429 Too Many Requests` when clients exceed policy and include retry guidance when possible.
• Design write endpoints so clients can safely retry after timeouts without creating duplicate side effects.
• For create or payment-style operations, use an idempotency key instead of trusting transport retries alone.

Content negotiation and errors

• The `Accept` header lets the client ask for JSON, CSV export, or specialized error media types.
• `application/problem+json` keeps errors predictable instead of inventing a different payload for every endpoint.
• This becomes more important as multiple clients, SDKs, and partner teams depend on the same API.

Problem details example

{
  "type": "https://example.com/problems/validation-error",
  "title": "Validation failed",
  "status": 400,
  "detail": "name is required",
  "instance": "/v1/items"
}

Hypermedia in practice

• Full HATEOAS is uncommon in many product APIs, but links still matter for pagination, related resources, and navigation.
• The HTTP `Link` header and formats such as HAL or JSON:API are practical ways to expose link relations.
• Even without full hypermedia, stable link patterns improve discoverability and client correctness.

Idempotency and retries

If a client times out, it may retry even though the server already created the record. Idempotency lets the server recognize that duplicate attempt and return the original result instead of creating a second row.

POST /api/orders
Idempotency-Key: order-20260325-00091
Content-Type: application/json
Authorization: Bearer TOKEN

{
  "customer_id": 44,
  "amount": 199.00,
  "currency": "USD"
}

Concurrency and consistency

• Two users updating the same record at the same time can overwrite each other if the API blindly accepts both writes.
• Use `updated_at`, version numbers, or ETags to detect that the record changed after the client last read it.
• Return `409 Conflict` when the client needs to re-fetch and retry with fresh data.

JSON_EXTRACT and JSON_SET

JSON columns are useful when some fields are flexible or nested. They let you store structured metadata while still updating only the path that changed.

-- Extract a JSON value
SELECT JSON_EXTRACT(metadata, '$.specs.mp') AS mp
FROM items
WHERE id = 1;

-- Update nested JSON fields
UPDATE items
SET metadata = JSON_SET(metadata, '$.flags.featured', true, '$.color', 'red')
WHERE id = 1;

Transactions for safe multi-step updates

When one API call changes multiple columns or tables, use a transaction so the write fully succeeds or fully rolls back.

START TRANSACTION;
UPDATE items SET name = 'Camera' WHERE id = 1;
UPDATE items
SET metadata = JSON_SET(metadata, '$.updatedBy', 'api')
WHERE id = 1;
COMMIT;

GET endpoint example

This is the classic "load data into the website" endpoint. It queries MySQL, fetches rows, and returns JSON.

<?php
header('Content-Type: application/json; charset=utf-8');

$pdo = new PDO($dsn, $user, $pass, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
]);

$stmt = $pdo->query('SELECT id, title, status, updated_at FROM articles ORDER BY id DESC LIMIT 10');
$rows = $stmt->fetchAll();

echo json_encode([
    'success' => true,
    'data' => $rows,
], JSON_UNESCAPED_UNICODE);

POST endpoint example

This creates a new row from a JSON body sent by a form, admin panel, or another service.

<?php
$payload = json_decode(file_get_contents('php://input'), true);

$stmt = $pdo->prepare('INSERT INTO articles (title, body, status) VALUES (:title, :body, :status)');
$stmt->execute([
    ':title' => $payload['title'],
    ':body' => $payload['body'],
    ':status' => $payload['status'] ?? 'draft',
]);

echo json_encode([
    'success' => true,
    'insert_id' => $pdo->lastInsertId(),
]);

Node.js lab

Express plus Sequelize works well for classic HTTP resource APIs, file uploads, and JSON column updates.

import express from "express";
import multer from "multer";

const app = express();
app.use(express.json());
const upload = multer({ dest: "uploads/" });

app.post("/v1/items", requireAuth, async (req, res) => {
  const item = await Item.create({ name: req.body.name, metadata: req.body.metadata || {} });
  res.status(201).json(item);
});

app.patch("/v1/items/:id/metadata", requireAuth, async (req, res) => {
  await sequelize.query(
    "UPDATE items SET metadata = JSON_SET(metadata, ?, CAST(? AS JSON)) WHERE id = ?",
    { replacements: [req.body.path, JSON.stringify(req.body.value), Number(req.params.id)] }
  );
  res.json(await Item.findByPk(req.params.id));
});

app.get("/v1/stream/items", requireAuth, async (req, res) => {
  res.setHeader("Content-Type", "text/event-stream");
  const timer = setInterval(async () => {
    res.write(`data: ${JSON.stringify({ count: await Item.count() })}\n\n`);
  }, 1000);
  req.on("close", () => clearInterval(timer));
});

FastAPI lab

FastAPI fits strongly typed Python services, SQLAlchemy sessions, and built-in WebSocket support.

@app.post("/v1/items", dependencies=[Depends(require_user)])
def create_item(payload: dict, db: Session = Depends(get_db)):
    item = Item(name=payload["name"], metadata=payload.get("metadata", {}))
    db.add(item)
    db.commit()
    db.refresh(item)
    return item

@app.patch("/v1/items/{item_id}/metadata", dependencies=[Depends(require_user)])
def json_set(item_id: int, payload: dict, db: Session = Depends(get_db)):
    db.execute(
        text("UPDATE items SET metadata = JSON_SET(metadata, :path, CAST(:value AS JSON)) WHERE id = :id"),
        {"path": payload["path"], "value": json.dumps(payload["value"]), "id": item_id},
    )
    db.commit()
    return db.get(Item, item_id)

@app.websocket("/ws")
async def ws(websocket: WebSocket):
    await websocket.accept()
    while True:
        msg = await websocket.receive_text()
        await websocket.send_text(json.dumps({"type": "echo", "msg": msg}))

Laravel lab

Laravel keeps migrations, model casting, validation, auth, and file handling in one familiar stack.

Schema::create('items', function (Blueprint $table) {
  $table->id();
  $table->string('name', 190);
  $table->json('metadata');
  $table->timestamps();
});

class Item extends Model {
  protected $fillable = ['name', 'metadata'];
  protected $casts = ['metadata' => 'array'];
}

class ItemController extends Controller {
  public function update(Request $request, int $id) {
    $item = Item::findOrFail($id);
    $patch = $request->input('metadataPatch', []);
    $item->metadata = array_merge($item->metadata ?? [], $patch);
    if ($request->has('name')) $item->name = $request->input('name');
    $item->save();
    return $item;
  }
}

Production risks to watch

• Schema changes that break older clients because fields moved or types changed.
• Background retries that create duplicates when idempotency is missing.
• Large JSON payloads that slow mobile clients and increase memory usage.
• Silent cache layers returning old data after a successful write.
• Missing rate limits that let one client overload a shared service.

Debugging order that works

1. Reproduce with one exact request in curl, Postman, or browser devtools.
2. Check the status code and response body before changing code.
3. Look up the request id or trace id in logs.
4. Inspect SQL and queue activity only after the request path is confirmed.
5. Add the missing guardrail so the same bug does not return.