Designing REST resources

API design: REST, HTTP, GraphQL and gRPC Junior Python 3.13+ PostgreSQL 17+ Reviewed 31 Oct 2026 By Best Latest Apps

Pick the fix

Which endpoint set follows REST conventions for creating and reading orders?

OptionsPOST /orders returns 201 with Location: /orders/42; GET /orders/42POST /createOrder; GET /getOrder?id=42GET /orders/create?item=…PUT /orders with the new order in the body

Hint 1 of 1

What does the HTTP method already say?

Choose an answer, then open Show answer below to check it.

Show answer

Answer: A POST /orders returns 201 with Location: /orders/42; GET /orders/42

Correct. The collection takes the POST; the new resource gets its own URL.

In REST the URL names a thing and the HTTP method says what to do with it. Creating means POSTing to the collection, and the server, which picks the id, returns the new URL in Location so the client can GET it.

Why not the others?

B POST /createOrder; GET /getOrder?id=42. Verbs in paths duplicate what the method already says.
C GET /orders/create?item=…. GET must not change state; caches and crawlers can trigger it.
D PUT /orders with the new order in the body. PUT replaces the target resource; the client doesn't know the new id.

30-second answer

Model nouns as resources and let HTTP methods carry the verbs: GET /orders, POST /orders, GET /orders/{id}, PATCH /orders/{id}, and nested items at /orders/{id}/items when they only exist inside an order. Use plural, lowercase, hyphenated path segments, put filters and sorting in query parameters, and return the created resource's URL in a Location header with 201.

Practise saying it · 35 s. No recording, just a timer

How do you design REST resources?

Say your answer out loud, then check which of these points you covered:

Nouns as resources, methods as verbs
Shallow nesting
Query params for filters
201 + Location
Consistency

Deep dive

Keep nesting shallow: one level is usually enough. Items with their own life can be top-level with a filter (/items?order_id=…).

Actions that aren't CRUD can be modelled as sub-resources (POST /orders/{id}/cancellation) or, sparingly, as POST /orders/{id}:cancel.

Design from the client's use cases, not from database tables.

Be consistent across the whole API: naming, casing of JSON fields, date formats, error shape.

Common mistakes

Verbs in paths: /getOrders, /createOrder.
Exposing table structure directly, including join tables.
Different casing and pagination styles in different endpoints.

Senior take & follow-ups

Show the resource list with methods, then the conventions and one non-CRUD action.

Follow-up questions

Think of your answer first, then open the hint.

How do you model 'cancel an order'?
Show hint
A state change via PATCH, or a cancellation sub-resource you POST to.
Plural or singular?
Show hint
Plural collections; it reads naturally for both the list and one item.

Similar on iOS: POST requests with a JSON body The app side builds the POST request; here you decide what the server returns.

Suggest a fix if something here is wrong or out of date.