API design

Enables hierarchical resource retrieval by scoping subresource access under a parent resource identifier in the URL path.

REST API design: exposing nested resources like comments under a blog post Web services: retrieving child entities scoped to a parent record API consumption: fetching related data via a parent-child URL path

REST APIs, HTTP routing, OpenAPI specifications, web frameworks (Flask, Express, Spring), microservices

GET /resource/{id}/subresource

GET /resource/{id}/subresource

resource: parent resource name (plural noun); id: unique identifier of the parent resource (string, int, or UUID); subresource: child resource name (plural noun)

• HTTP method verbs (GET
• POST
• PUT
• DELETE)
• path parameters
• query strings
• JSON response bodies
• authentication headers
• pagination parameters

• Query parameters instead of path parameters: /resource?id={id}&subresource=true — less RESTful and harder to cache Flat resource with embedded subresources: /subresource/{id} — loses hierarchical context GraphQL queries: more flexible but heavier infrastructure and no HTTP caching

Using POST instead of GET for read operations: violates HTTP semantics and prevents proxy caching Omitting pluralization: /resource/{id}/subresource vs /resources/{id}/subresources — inconsistent with REST naming conventions Not URL-encoding the id: special characters like spaces or slashes cause routing failures or unintended path segments Returning 200 with an error body instead of 404: obscures missing resources from clients and breaks HTTP semantics Exposing sequential database IDs without validation: enables enumeration attacks against parent resources

GET /resource/{id}: retrieves the parent resource alone without children GET /resource/{id}/subresource/{sub_id}: retrieves a specific subresource item rather than the collection GET /subresource?parent_id={id}: flat alternative using query parameters instead of path nesting

Coming from SOAP: may expect a single endpoint with action parameters — REST uses resource-oriented URLs with HTTP verbs as the action Coming from RPC: may pass IDs in the request body — REST path parameters belong in the URL for cacheability and bookmarkability

• REST endpoint patterns
• HTTP method routing
• path parameter conventions
• nested resource design
• collection vs item endpoints

When NOT to use: when the subresource has no meaningful parent relationship, or when nesting exceeds 2-3 levels (flatten the hierarchy or use query filters instead) Performance: path parameters are cacheable by CDNs and proxies; deep nesting increases URL length and parsing overhead per request Boundary conditions: verify the authenticated user has access to the parent resource before returning subresources, and return 404 (not 403) when the parent does not exist to avoid leaking existence

Provides a predictable, cacheable, and bookmarkable URL structure that clearly expresses the parent-child data relationship and enables HTTP-level optimizations by proxies and CDNs.

Like a library catalog: first find the shelf (resource), then the book number (id), then the chapter (subresource) — each level narrows the scope of what you retrieve.

GET /resource/{id}/subresource/{sub_id} — retrieving a specific subresource item by its own identifier