REST API

REST API

Representational State Transfer (REST) is the architectural style for distributed hypermedia systems. It relies on stateless, client-server, cacheable communications protocols (mostly HTTP).

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

Everything is a resource identified by a URI (/users/123).

HTTP Verbs

Use verbs to define actions, not URIs.

• GET /orders (List)
• POST /orders (Create)
• PATCH /orders/1 (Update partial)
• DELETE /orders/1 (Remove)

Statelessness

Each request must contain all information necessary to understand the request. The server accepts no session state.

Common Patterns

Filtering, Sorting, Pagination

Standard query params: ?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

Do:

• 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:

• 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

References

• Restful API Design (Microsoft)
• Richardson Maturity Model

Source: G1Joshi/Agent-Skills — distributed by TomeVault.