REST组合场景下API设计咨询：保障关联实体一致性

Got it, let's tackle this REST API design problem where TestResult and TestCaseResults have a strict composition relationship—meaning a TestResult isn't valid unless it has all its associated TestCaseResults. The standard nested resource approach (like /api/testresults/1/testcaseresults) falls short here because it lets clients manipulate TestCaseResults independently, which breaks the consistency rule. Here's how to design it properly:

Since TestResult and TestCaseResults are a composition (not just an association), TestResult should be the only top-level resource. TestCaseResults are part of its internal state, not independent resources. This enforces that every operation maintains the required consistency.

Full REST Endpoint Set #

1. Create a Complete TestResult #

Use a POST request to create the entire aggregate in one go—no partial creations allowed:

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

Request body must include all TestResult fields plus the full set of TestCaseResults:

{
  "testName": "Checkout Flow End-to-End",
  "executionTimestamp": "2024-05-21T09:15:00Z",
  "environment": "staging",
  "testCaseResults": [
    {
      "caseId": "tc-checkout-001",
      "caseDescription": "Add item to cart",
      "status": "PASS",
      "executionTimeMs": 450
    },
    {
      "caseId": "tc-checkout-002",
      "caseDescription": "Apply discount code",
      "status": "FAIL",
      "executionTimeMs": 620,
      "failureReason": "Discount code validation timed out"
    },
    {
      "caseId": "tc-checkout-003",
      "caseDescription": "Complete payment",
      "status": "PASS",
      "executionTimeMs": 1200
    }
  ]
}

Server validation: Reject requests with missing/incomplete testCaseResults (e.g., empty array, missing required fields like status) with a 400 Bad Request and clear error message.

2. Retrieve a Complete TestResult #

Fetch the full aggregate in one response to ensure clients always get consistent data:

GET /api/testresults/{testResultId}

Response body returns the entire TestResult including all TestCaseResults—no need for separate endpoints to fetch child entities.

3. Update the Entire TestResult (Replace All TestCaseResults) #

Use PUT to replace the entire resource. Clients must submit the full updated TestResult, including the complete set of TestCaseResults:

PUT /api/testresults/{testResultId}
Content-Type: application/json

Request body follows the same structure as the POST request. The server will overwrite the existing TestResult entirely—this guarantees that after the update, the TestResult is still consistent with all required TestCaseResults.

4. Delete a TestResult (And All Its TestCaseResults) #

Deleting the aggregate root automatically removes all associated TestCaseResults (since they can't exist independently):

DELETE /api/testresults/{testResultId}

Return 204 No Content on success.

Handling Partial Updates (If Absolutely Necessary) #

If clients need to modify parts of the TestResult or its TestCaseResults without re-submitting the entire resource, use PATCH—but force clients to submit the full updated set of TestCaseResults (never allow modifying individual TestCaseResults in isolation).

For example, to update the status of one TestCaseResult, the client must send a JSON Patch operation that replaces the entire testCaseResults array:

PATCH /api/testresults/{testResultId}
Content-Type: application/json-patch+json

Request body:

[
  {
    "op": "replace",
    "path": "/testCaseResults",
    "value": [
      {
        "caseId": "tc-checkout-001",
        "caseDescription": "Add item to cart",
        "status": "PASS",
        "executionTimeMs": 450
      },
      {
        "caseId": "tc-checkout-002",
        "caseDescription": "Apply discount code",
        "status": "PASS", // Updated status
        "executionTimeMs": 620,
        "failureReason": null
      },
      {
        "caseId": "tc-checkout-003",
        "caseDescription": "Complete payment",
        "status": "PASS",
        "executionTimeMs": 1200
      }
    ]
  }
]

The server validates that the new testCaseResults array is complete before applying the patch.

Why Nested Resources Are a Bad Fit Here #

The problem with endpoints like /api/testresults/1/testcaseresults is that they let clients:

• Create a TestResult first, then add TestCaseResults one by one—leaving the TestResult in an invalid, incomplete state for some time
• Update or delete individual TestCaseResults, which breaks the "TestResult must include all TestCaseResults" rule
• Fetch partial data (just TestCaseResults) which might lead clients to make decisions based on inconsistent state

By making TestCaseResults part of the TestResult's internal state, you eliminate these risks entirely.

Server-Side Guardrails to Enforce Consistency #

Add these validation rules to your backend:

• Require testCaseResults to be present and non-empty (or match a business-specific minimum count) on POST and PUT
• Validate that every TestCaseResult has all required fields (e.g., caseId, status)
• Check for duplicate caseId values in the testCaseResults array
• Block any attempts to access standalone TestCaseResults endpoints (e.g., /api/testcaseresults/{caseId}) with 404 Not Found or 405 Method Not Allowed

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