API-003: POST Creation Endpoints Must Return 201 Created

Attribute	Value
Category	API Design
Default Severity	warning
Applicable Files	Controller files (*.controller.ts, *.router.ts)

Why It Exists (Rationale)

RFC 7231 specifies that when a POST request results in the creation of a new resource, the server should return HTTP status 201 Created with a Location header or payload referencing the created resource.

Returning 200 OK indicates generic success without signaling that persistence was established.

Bad Example

router.post("/orders", async (req, res) => {
  const newOrder = await orderService.create(req.body);
  // ❌ Returns default 200 OK instead of 201 Created
  return res.status(200).json(newOrder);
});

Good Example

router.post("/orders", async (req, res) => {
  const newOrder = await orderService.create(req.body);
  // ✅ Returns HTTP 201 Created
  return res.status(201).json(newOrder);
});

How It's Detected

ArchStandards inspects POST handler AST declarations, checking response status codes.