REST Resource Design and HTTP Status Behavior
Designing an API's resources and status codes from the implementer's side — the same conventions this curriculum's testing courses teach testers to verify.
What you'll learn
- Design a resource's URL and method structure following REST conventions
- Choose the correct status code for a given outcome, from the server-implementer's side
- Explain why response shape should stay consistent across every endpoint in an API
Prerequisites
Explanation
Designing an API's resources is the same REST convention this curriculum's API Testing and Automation course teaches testers to verify — now from the side that has to decide it in the first place. A resource (enrollments) gets a predictable set of endpoints: GET /enrollments (list), GET /enrollments/:id (one), POST /enrollments (create), PATCH /enrollments/:id (partial update), DELETE /enrollments/:id (remove) — the same mapping from earlier in this course's Express-structure lesson, now applied deliberately as a design decision rather than encountered as a given.
Choosing the right status code is part of the API's actual contract, not an afterthought. A newly created resource should return 201 Created, not a generic 200 — the distinction tells a well-behaved client something concrete happened, distinct from merely reading data that already existed. A successful DELETE conventionally returns 204 No Content (there's nothing left to describe) rather than 200 with an empty body. A resource that doesn't exist returns 404; a malformed request returns 400; a request whose data conflicts with the resource's current state (an enrollment for a course that no longer exists) returns 409 Conflict. Each of these is a deliberate signal to the client about what kind of situation occurred — collapsing everything into a generic "it failed" (or worse, always returning 200 with an error field in the body, the exact anti-pattern this curriculum's testing courses teach as a real defect) throws away information a well-built client could otherwise act on correctly.
Response shape consistency matters as much as any individual status code. Every success response in a well-designed API follows the same envelope; every error response follows the same envelope (the { error: { code, message, fields } } shape from the previous lesson, used everywhere, not just on the one route where it was first written). A client integrating with the API writes error-handling code once, generically, instead of special-casing each endpoint's slightly different error shape.
Example
A status-code decision function -- the exact judgment call a route handler makes, made explicit and testable on its own.
function statusForOutcome(outcome) {
switch (outcome) {
case "created": return 201;
case "deleted": return 204;
case "not-found": return 404;
case "validation-failed": return 400;
case "conflict": return 409;
default: return 200;
}
}
console.log(statusForOutcome("created")); // 201
console.log(statusForOutcome("deleted")); // 204
console.log(statusForOutcome("not-found")); // 404Try it yourself
Add a case for 'read' (a normal successful GET) mapping to 200, then test it.
Code editor. Press Escape then Tab to leave the editor if keyboard focus becomes trapped. Press Control+Shift+M inside the editor to toggle Tab-key focus trapping.
Guided exercise
Guided exercise
Using statusForOutcome already defined, determine the correct status for three server actions and store each: statusForNewEnrollment (a successful create), statusForDeletedEnrollment (a successful delete), statusForMissingCourse (the referenced course does not exist).
Checks: correctly maps a create outcome · correctly maps a delete outcome · correctly maps a not-found outcome
Code editor. Press Escape then Tab to leave the editor if keyboard focus becomes trapped. Press Control+Shift+M inside the editor to toggle Tab-key focus trapping.
Stuck? Get a hint.
Independent exercise
Independent exercise
Write buildSuccessEnvelope(data) returning { data } (a consistent success wrapper), and buildErrorEnvelope(code, message) returning { error: { code, message } } (a consistent error wrapper) -- modeling response-shape consistency across an entire API.
Checks: wraps success data consistently · wraps error data consistently
Code editor. Press Escape then Tab to leave the editor if keyboard focus becomes trapped. Press Control+Shift+M inside the editor to toggle Tab-key focus trapping.
Stuck? Get a hint.
Common mistakes
- Returning 200 for a newly created resource instead of 201, losing the distinction between reading existing data and creating something new.
- Returning 200 with an `error` field in the body instead of a real 4xx/5xx status — the exact status/body mismatch defect from this curriculum's API testing course, now viewed from the side that would introduce it.
- Using a different response shape (sometimes a bare array, sometimes a wrapped object, sometimes a differently-named error field) across different endpoints of the same API.
Knowledge check
Takeaway
REST resource and status-code design is a real, deliberate contract with the client — the correct status code and a consistent response envelope communicate real information a well-built client can act on.
Summary
This lesson covered designing resource endpoints and choosing the correct status code for a given outcome, plus why consistent success/error response shapes matter across an entire API, from the implementer's side of the same conventions taught in this curriculum's testing courses.
References
Your notes
Notes save automatically.
Finished this lesson?
Mark it complete to track your progress and schedule a future review.
AI tutor
The optional AI tutor isn't enabled in this deployment. All lessons, exercises, quizzes, and search work fully without it.