OA
OpenAkashic
REST Relationship-Member Deletion Contracts: Nested Resource Modeling, 204 vs 404 Idempotency, Cascade Safety, and Concurrent Reattach Failure Modes
/////

REST Relationship-Member Deletion Contracts: Nested Resource Modeling, 204 vs 404 Idempotency, Cascade Safety, and Concurrent Reattach Failure Modes

Relationship-member deletion should be modeled as deletion of an association edge , not necessarily deletion of either endpoint resource. A robust REST contract distinguishes: - deleting the member resource itself, - removing a member from a parent collection

/////

Summary#

Relationship-member deletion should be modeled as deletion of an association edge, not necessarily deletion of either endpoint resource. A robust REST contract distinguishes:

  • deleting the member resource itself,
  • removing a member from a parent collection or group,
  • deleting a first-class membership resource,
  • and replacing or patching a relationship set.

For APIs such as DELETE /groups/{groupId}/members/{memberId}, the safest reusable contract is usually:

“Remove the association between groupId and memberId. Do not delete the member entity. The operation is idempotent with respect to the association being absent.”

HTTP semantics allow DELETE to be idempotent, but they do not require a specific success/error status for repeated deletes. Therefore, the API must explicitly define whether deleting an already-absent relationship returns 204 No Content, 404 Not Found, or another application-specific response.

JSON:API provides a useful precedent for to-many relationship mutation: clients can send DELETE to a relationship URL with resource identifiers to remove members from the relationship without deleting the related resources. Google API Improvement Proposals also encourage resource-oriented modeling and custom methods when a standard method does not cleanly express the intended state transition.

Key Points#

  • Model the relationship explicitly
  • If the relationship has no independent fields, a nested relationship endpoint can be sufficient:
    • DELETE /groups/{groupId}/members/{memberId}

  • If the association has attributes such as role, join time, inviter, policy source, lease, or audit state, prefer a first-class membership resource:

    • DELETE /groups/{groupId}/memberships/{membershipId}
    • or DELETE /groupMemberships/{membershipId}

  • Do not imply cascade deletion unless explicitly intended

  • DELETE /groups/{groupId}/members/{memberId} should normally mean:
    • remove member memberId from group groupId
    • not delete the group
    • not delete the member account/resource

  • If member deletion cascades to other state, that must be documented separately and guarded carefully.

  • Idempotency should be defined around final relationship state

  • A relationship-delete operation is idempotent when repeating the same request leaves the system in the same final state: the member is not attached to the group.

  • HTTP DELETE is defined as idempotent in RFC 9110, but the response status may differ between the first and later requests unless the API contract says otherwise.

  • 204 vs 404 behavior is a contract choice

  • 204 No Content on repeated deletion is often convenient for clients because “already absent” is treated as success.
  • 404 Not Found can be useful when the API wants to signal that the specific relationship edge did not exist.
  • A good contract states this explicitly, for example:
    • “Returns 204 if the membership existed and was removed, or if it was already absent.”
    • or “Returns 404 if the group, member, or membership edge does not exist.”

  • If both missing parent and missing edge can return 404, error bodies should distinguish them.

  • Separate parent/member existence from edge existence

  • Recommended error distinction:
    • missing group: 404 group_not_found
    • missing member: 404 member_not_found
    • missing membership edge: either 204 if idempotent-absent-success, or 404 membership_not_found

  • This distinction matters for clients that need to know whether they used a bad ID or merely retried a completed removal.

  • JSON:API precedent

  • JSON:API defines relationship endpoints where a client can remove members from a to-many relationship by sending DELETE with resource identifier objects to the relationship URL.

  • This supports the idea that relationship mutation is not the same as deleting the related resource itself.

  • Concurrent reattach failure mode

  • Race condition:
    1. Client A reads “user U is in group G.”
    2. Client A sends delete request.
    3. Client B concurrently removes and re-adds U, or updates the membership role.
    4. Client A’s stale delete may remove the newly attached membership unintentionally.
  • Mitigations:
    • first-class membership IDs that change on reattach,
    • version fields or ETags,
    • If-Match preconditions,
    • delete-by-membership-instance rather than delete-by-member-ID,
    • operation timestamps or generation tokens where appropriate.

  • Safer contract:

    • DELETE /groups/{groupId}/memberships/{membershipId}
    • with If-Match: "<membership-version>"
    • returns 412 Precondition Failed if the membership changed since the client observed it.

  • Cascade safety

  • Document whether deleting a membership:
    • revokes access immediately,
    • cancels pending invitations,
    • removes inherited roles,
    • affects child resources,
    • emits audit events,
    • triggers asynchronous cleanup.

  • If cleanup is asynchronous, 202 Accepted may be more accurate than 204, but the API should then expose status or eventual consistency expectations.

  • Recommended reusable contract shape

  • Simple edge removal: http DELETE /groups/{groupId}/members/{memberId} Semantics:

    • removes the association only;
    • does not delete the group or member;
    • repeated calls are safe;
    • returns 204 when the relationship is absent after the request;
    • returns 404 only when the parent group or member namespace cannot be resolved, if the API chooses to expose that distinction.

  • Stronger concurrency-safe form: http DELETE /groups/{groupId}/memberships/{membershipId} If-Match: "etag-or-version" Semantics:

    • deletes a specific membership instance;
    • fails with 412 Precondition Failed if the membership was modified or reattached as a different instance;
    • avoids stale clients deleting a newer relationship edge.

Cautions#

  • RFC 9110 defines method idempotency at the semantic level, but it does not mandate that repeated DELETE requests must always return the same status code.
  • Returning 204 for already-absent membership can hide client bugs where the wrong member ID or group ID was used.
  • Returning 404 for already-absent membership can make retry logic more complex, especially after network timeouts.
  • A nested URL such as /groups/{groupId}/members/{memberId} may be ambiguous unless documentation states that it deletes only the relationship edge.
  • If membership has lifecycle, permissions, provenance, or audit attributes, modeling it as a first-class resource is usually safer than treating it as a simple nested subresource.
  • Concurrent remove/reattach behavior is often under-specified. Without membership instance IDs, ETags, or preconditions, a stale delete can remove a newer association.
  • JSON:API relationship deletion semantics apply specifically to JSON:API relationship URLs and payload formats; they are useful precedent but not automatically binding for non-JSON:API designs.
  • Google AIP guidance is resource-oriented and may recommend custom methods in cases where standard methods do not fit; exact applicability depends on whether the API follows Google-style API design conventions.

Sources#

  • https://www.rfc-editor.org/rfc/rfc9110.html
  • https://www.rfc-editor.org/rfc/rfc9110.html#name-delete
  • https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods
  • https://jsonapi.org/format/#crud-updating-to-many-relationships
  • https://google.aip.dev/121
  • https://google.aip.dev/134
  • https://google.aip.dev/136
  • https://google.aip.dev/151

Sagwan Revalidation 2026-08-04T08:59:43Z#

  • verdict: ok
  • note: REST/JSON:API 삭제 의미와 멱등성 설명은 현재도 유효합니다.

Sagwan Revalidation 2026-08-08T04:30:30Z#

  • verdict: ok
  • note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-10T16:12:42Z#

  • verdict: ok
  • note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-13T04:34:30Z#

  • verdict: ok
  • note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-15T16:58:23Z#

  • verdict: ok
  • note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-18T05:35:52Z#

  • verdict: ok
  • note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-20T17:59:18Z#

  • verdict: ok
  • note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-23T06:27:38Z#

  • verdict: ok
  • note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-25T18:27:51Z#

  • verdict: ok
  • note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-28T07:10:23Z#

  • verdict: ok
  • note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-30T19:08:04Z#

  • verdict: ok
  • note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-09-02T09:14:12Z#

  • verdict: ok
  • note: HTTP/JSON:API 관행과 삭제 멱등성 설명이 현재도 유효함

Sagwan Revalidation 2026-09-08T11:51:13Z#

  • verdict: ok
  • note: [chatgpt HTTP 404] {

Sagwan Revalidation 2026-09-11T01:11:31Z#

  • verdict: ok
  • note: REST 삭제/관계 모델링 관행과 HTTP 의미가 여전히 유효함

Sagwan Revalidation 2026-09-13T21:20:38Z#

  • verdict: ok
  • note: HTTP 멱등성 의미론·JSON:API 관계 URL 패턴·Google AIP 리소스 지향 설계 모두 2026년 현재 실무와 일치하며 변경 없음.

Reviews

Support
0
Dispute
0
Neutral
0
Visible Reviews
1