REST多版本实体的资源标识与接口设计规范咨询

Great question—this is a super common pain point when building REST APIs with versioned resources, especially when some attributes stay consistent across versions while others evolve. Let’s break this down step by step.

First: Should /things/1/subthings be allowed if /things/1 is "illegal"? #

Technically, you can implement this endpoint, but it goes against REST’s core principle of resource hierarchy. REST relies on identifiers pointing to meaningful resources—if /things/1 isn’t a valid resource, its child path /things/1/subthings loses its semantic anchor. Users (and other developers) would reasonably wonder: "What is /things/1 if I can’t access it, but can access its subresources?"

A better approach is to redefine /things/1 as a metadata/collection resource for all versions of the entity, rather than marking it as illegal. For example:

• GET /things/1 returns stable attributes (id, name) plus a list of version links:

  {
    "id": 1,
    "name": "My Thing",
    "versions": ["/things/1/v1", "/things/1/v2"]
  }
  

This way, /things/1/subthings makes perfect semantic sense—it refers to all subthings across all versions of thing 1, and the parent resource is valid and useful.

Standard & Feasible Approaches for Versioned Entities #

There’s no single "official" standard, but these are the most widely adopted patterns in production APIs:

1. Version as a Path Segment (Your Proposed Approach) #

This is the most explicit and intuitive pattern:

• GET /things/1/v1 → Version 1 of the Thing
• GET /things/1/v2 → Version 2 of the Thing

To handle stable attributes:

• Keep them in the parent resource /things/1 (as mentioned above) to avoid duplication across versions.
• When returning a versioned entity (e.g., /things/1/v1), you can include the stable attributes alongside version-specific ones, or link back to /things/1 for them.

Pros: Clear URL structure, easy to bookmark/share, works well with caching.
Cons: URLs get longer, and you need to manage the parent resource’s metadata.

2. Version as a Query Parameter #

If versions are optional (e.g., default to the latest version), use a query param:

• GET /things/1 → Latest version of the Thing
• GET /things/1?version=v1 → Specific version

For cross-version subresources:

• GET /things/1/subthings?version=all → All subthings across versions

Pros: Keeps URLs clean, easy to add new versions without changing path structure.
Cons: Less explicit than path segments, and query params can be overlooked in caching strategies.

3. Version via HTTP Headers #

Use a custom header (like Accept-Version) to specify the version, keeping the resource path clean:

• GET /things/1 with Accept-Version: v1 → Version 1
• GET /things/1 with Accept-Version: v2 → Version 2

This aligns with REST’s idea of "representations"—the resource (/things/1) is the same, but you’re requesting different representations of it.

Pros: Maintains a single resource identifier, avoids URL clutter.
Cons: Less visible to users, harder to bookmark, and cross-version queries (like all subthings) require additional endpoints since headers are per-request.

4. Separate Stable vs. Versioned Attributes #

Split the entity into two layers:

• GET /things/1 → Stable attributes (id, name) + version list
• GET /things/1/versions/v1 → Version-specific attributes (subthings, dynamic fields)

For cross-version subresources:

• GET /things/1/versions/all/subthings → Explicit endpoint for all subthings across versions

Pros: Clean separation of concerns, makes it clear which attributes are stable vs. evolving.
Cons: Adds more endpoints to manage.

Key Takeaway #

The best approach depends on your use case:

• Use path segments if versions are core to resource identity (e.g., immutable historical versions).
• Use headers if versions are just different representations of the same logical entity.
• Always avoid marking the parent resource (/things/1) as illegal—it breaks REST’s semantic model and creates confusion for API consumers.

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