REST API

When to Use

• Public APIs: The universal standard; easiest for 3rd parties to consume.
• Simple Resource Access: Perfect for CRUD (Create, Read, Update, Delete) operations.
• Caching: When you need to leverage HTTP caching (CDNs, Browsers).

Quick Start

// Express.js Example
app.get("/users/:id", async (req, res) => {
  const user = await db.find(req.params.id);
  if (!user) return res.status(404).json({ error: "Not Found" });

  // HATEOAS (Hypermedia As The Engine Of Application State) - optional but "True REST"
  res.json({
    ...user,
    links: {
      self: `/users/${user.id}`,
      orders: `/users/${user.id}/orders`,
    },
  });
});

Core Concepts

Resources

/users/123

HTTP Verbs

• GET /orders

  (List)

• POST /orders

  (Create)

• PATCH /orders/1

  (Update partial)

• DELETE /orders/1

  (Remove)

Statelessness

Common Patterns

Filtering, Sorting, Pagination

?sort=-created_at&limit=10&page=2&status=active

Versioning

• URI Versioning:

  /v1/users

  (Most common).
• Header Versioning:

  Accept: application/vnd.myapi.v1+json

  .

Best Practices

• Use proper HTTP Status Codes (200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Server Error).
• Use Snake Case (

  user_id

  ) in JSON responses (standard convention) or camelCase if consistent with JS ecosystem.
• Implement Rate Limiting to protect resources.

• Don't use GET for state-changing operations.
• Don't return 200 OK for errors (e.g.,

  { "error": "failed" }

  with status 200).
• Don't expose database IDs if possible (use UUIDs).

Troubleshooting

405 Method Not Allowed

415 Unsupported Media Type

Content-Type: application/json

CORS Error

Access-Control-Allow-Origin

References

• Restful API Design (Microsoft)
• Richardson Maturity Model