RESTful端点设计咨询：筛选指定日期范围内最新创建的子资源

Great question—this is a super common REST design problem where you have to balance strict resource semantics with practical client needs. Let’s walk through some better approaches that solve your pain points, and clarify a common misconception about REST along the way.

First, let’s address your worry about the /latest endpoint: REST doesn’t ban endpoints that return dynamically changing results! The key rule is that the semantic purpose of the resource stays consistent. If an endpoint like /main-resources/{id}/sub-resources/latest-containing?date=YYYY-MM-DD always means "the most recently created sub-resource under this main resource whose time interval includes the given date", that’s a stable, well-defined resource—even if the actual data returned shifts as new sub-resources are added. Your initial concern about violating REST was a bit misplaced, but we can refine the endpoint to be even clearer.

Here are three solid, practical options to consider:

1. Explicit, Purpose-Built Sub-Resource Endpoint #

Stick with a dedicated endpoint but make its intent impossible to misinterpret:

GET /main-resources/{id}/sub-resources/latest-containing?date=2018-11-11

• Why this works: The endpoint name directly tells clients exactly what they’re getting. It returns a single sub-resource object (not a list), so clients don’t have to fumble with parsing a 1-element array—clean and straightforward.
• REST compliance: This counts as a computed resource with a fixed semantic identity, which is fully allowed under REST. The fact that the underlying data changes doesn’t break the resource’s core purpose.

2. Business-Aligned Endpoint (If Your Domain Has a Term for It) #

If your sub-resources map to a specific business concept (like "subscription periods", "coverage windows", or "active sessions"), replace the generic "latest-containing" with a domain-specific term:

GET /main-resources/{id}/active-coverage-window?date=2018-11-11

• Why this works: This ties your API directly to your business language, making it way more intuitive for both your dev team and stakeholders. It frames the resource as a meaningful business entity instead of just a technical filter result.
• REST fit: This is the most RESTful approach because it models a real-world concept from your domain, not just a filtered subset of data.

3. Reuse the List Endpoint with Content Negotiation #

If you want to avoid duplicating endpoints but hate returning a list for a single result, use content negotiation to let clients request a single object:

• Keep your flexible list endpoint as is:

  GET /main-resources/{id}/sub-resources?date=2018-11-11&sort=-createdAt&limit=1
  

• Add a custom media type (e.g., application/vnd.your-app.single-sub-resource+json) that tells your server to return a single object instead of an array. Clients send this in the Accept header:

  Accept: application/vnd.your-app.single-sub-resource+json
  

• Why this works: It reuses your existing list infrastructure, keeps flexibility (clients can still request the full list using the standard media type), and spares clients from handling unnecessary arrays.
• REST compliance: This leverages REST’s built-in content negotiation feature, which is a core part of the architectural style.

Which Option Should You Pick? #

• Go with Option 1 if you don’t have a specific business term for the resource and want a simple, clear endpoint that gets the job done.
• Go with Option 2 if your sub-resources have a well-defined business role—this will make your API more maintainable and intuitive long-term.
• Go with Option 3 if you need to support both list and single-item use cases without building separate endpoints.

内容的提问来源于stack exchange，提问作者Juan Vega