Design and consume RESTful APIs that exchange JSON, including resource modelling, request methods and status codes

Endpoints:

Error cases: 400 (bad input), 401 (not logged in), 403 (not allowed), 404 (not found).

Example - creating a task:

POST /api/tasks
Authorization: Bearer ...
Content-Type: application/json

{"title": "Study Module 2", "due": "2026-06-15"}

Response:

HTTP/1.1 201 Created
Location: /api/tasks/42
Content-Type: application/json

{"id": 42, "title": "Study Module 2", "due": "2026-06-15", "done": false}

Markers reward consistent resource-named paths (plural noun for the collection), correct method/code combinations (POST returning 201 with Location header, DELETE returning 204), a real JSON example with status line, and recognising that PATCH (partial update) and PUT (full replace) are distinct.

Marking criteria: 1 mark for the correct method on each of the three rows (all three needed for the mark), 1 mark for nesting the comment under its parent post with a plural collection noun, 1 mark for the correct success status on each row (201 with no body content expectation, 204 with no body).

Why it is not RESTful. The verb "delete" appears in the URL path, duplicating the job of the HTTP method, and the method used is POST rather than DELETE, so the request does not map onto the standard verb-to-action convention that REST tooling and caches rely on.

RESTful rewrite.

The resource (post 19) is identified purely by its path; the HTTP method DELETE conveys the action, so no verb is needed in the URL.

Marking criteria: 1 mark for identifying the verb-in-URL problem, 1 mark for identifying the wrong HTTP method (POST instead of DELETE), 1 mark for a correct RESTful rewrite with method, path and status code.

Line 2 breaks the convention. It uses GET (meant to be safe and read-only) to actually delete a resource, and puts the verb "delete" in the URL instead of using the DELETE method on /api/orders/17. A GET that mutates data is dangerous because browsers, crawlers and caches can trigger GET requests without the user intending a delete.

Line 3 breaks the convention. A successful POST that creates a new order should return 201 Created (with a Location header pointing to the new resource), not 200 OK, which is reserved for a successful read or update of an existing resource.

Lines 1 and 4 are correctly formed (GET returning 200 for a read, DELETE returning 204 for a removal with no body).

Marking criteria: 1 mark for identifying line 2 as faulty, 1 mark for correctly explaining why (GET should be safe/read-only; verb in URL), 1 mark for identifying line 3 as faulty, 1 mark for correctly explaining why (POST creation should return 201, not 200).

Endpoint table.

Example - creating a loan.

POST /api/loans
Content-Type: application/json

{"bookId": 204, "studentId": 51}

Response:

HTTP/1.1 201 Created
Location: /api/loans/900

{"id": 900, "bookId": 204, "studentId": 51, "returned": false}

Marking criteria: 1 mark for a resource-named GET on books, 1 mark for a correctly designed POST that creates a loan resource, 1 mark for using PATCH (not DELETE) to mark a return since the loan record is kept, not removed, 1 mark for correct status codes throughout, 1 mark for a complete, correctly formatted example JSON request and response pair with a Location header.

The problem. The response leaks two fields that should never reach the client: passwordHash (an attacker who intercepts or is served this response gains material to attempt an offline crack) and isInternalAdmin (an internal implementation flag that exposes system structure and could be tampered with if the client ever echoes it back on a write).

Corrected response.

{"id": 12, "name": "Priya"}

The API should map the database row to an explicit "public view" of the resource rather than serialising the raw row, so new sensitive columns added later do not automatically leak.

Marking criteria: 1 mark for identifying the password hash leak, 1 mark for identifying the internal flag leak, 1 mark for explaining the general principle (map explicitly, never serialise raw rows), 1 mark for a corrected JSON example containing only safe fields.

This is a 6-mark explain-and-justify: markers reward a correct technical distinction, correct use of idempotency, and a reasoned choice with a consequence, not just a definition.

PUT vs PATCH

PUT is defined to REPLACE the entire resource representation at a URL: any field the client omits from the PUT body is treated as absent (often reset to null or a default) in the stored resource. PATCH is defined to apply a PARTIAL update: only the fields present in the PATCH body are changed, and every other field is left untouched.

Idempotency

Both PUT and DELETE are idempotent by definition: sending the same PUT request N times leaves the resource in the same final state as sending it once, because it always sets the full state to the same values. PATCH is not guaranteed idempotent in general (e.g. a PATCH that increments a counter gives a different result each time it is repeated), though a PATCH that simply sets a field to a fixed value behaves idempotently in practice.

Choice for the todo API

To mark just the done field true on /api/tasks/{id}, PATCH is the correct choice: PATCH /api/tasks/42 {"done": true} changes only that one field and leaves title, due and any other fields exactly as they were.

Consequence of using PUT instead

If a client sent PUT /api/tasks/42 {"done": true} without re-sending title and due, a server that implements PUT correctly (full replace) would wipe those fields to null or default, silently destroying data the client did not intend to touch. This is a common real bug when developers use PUT as if it were PATCH.

Marker's note: full marks require (1) a correct definition of both methods in terms of replace vs partial update, (2) a correct statement of idempotency for both PUT and DELETE, (3) PATCH justified as the correct choice with a syntactically plausible request, and (4) a concrete, correctly reasoned consequence of using PUT wrongly (data loss on omitted fields), not just "it would be wrong".

This is a 7-mark evaluate-and-redesign: markers reward a structured critique against named REST principles followed by a concrete, internally consistent redesign, not just a list of complaints.

Evaluation.

• Verbs in URLs. /getAllUsers, /removeUser and /saveUser all encode the action in the path, duplicating the job the HTTP method should do; this makes the API harder to route through standard tooling (proxies, caches, generated clients) that expect method-driven behaviour.
• Wrong or overloaded methods. /removeUser uses GET to perform a destructive delete, which is unsafe because GET requests can be triggered by prefetching, crawlers or browser history without user intent. /saveUser overloads a single POST endpoint for two different operations (create and edit) that REST would separate by method (POST to create, PATCH or PUT to edit an existing user).
• Status codes carry no meaning. Returning 200 unconditionally, with success/failure buried in a body field, breaks every piece of standard tooling that inspects the HTTP status line (load balancers, monitoring, fetch/axios error handling, caching rules), and forces every consumer to parse the body just to know if the call worked.

Redesign.

Failures return the matching error status (400 invalid input, 404 unknown user) with an error body, instead of 200 with a hidden "ok" field.

Marker's note: top marks require (1) naming at least two distinct REST violations with the mechanism explained (not just "it's bad practice"), (2) explicitly identifying the unsafe GET-that-deletes as a correctness/security issue, (3) a complete redesigned table using plural-noun paths and the correct method-to-action mapping, and (4) explaining why status codes must reflect real success/failure rather than always returning 200.