diff --git a/ipa/general/0004.md b/ipa/general/0004.md index a50ac93..5947781 100644 --- a/ipa/general/0004.md +++ b/ipa/general/0004.md @@ -48,9 +48,11 @@ To learn more, see [IPA-127](0127.md). ### Side Effects -Side effects are those operations that may create or update resources unrelated -to the original request, for example, a create operation that also updates a -parent resource state. +Side effects are operations that create, update, or delete resources — or mutate +[client-owned fields](0111.md#single-owner-fields) of a resource — unrelated to +the target of the original request. For example, a create operation that also +updates a parent resource's configuration, or an update on resource X that +silently rewrites client-owned fields on resource Y. ### Governing API body diff --git a/ipa/general/0103.md b/ipa/general/0103.md index 9302629..a81a4fb 100644 --- a/ipa/general/0103.md +++ b/ipa/general/0103.md @@ -17,6 +17,15 @@ that a service can perform on behalf of the consumer. - Standard methods **must not** cause side effects - In such scenarios where a side effect is necessary, a custom method **should** be used + - A side effect specifically includes mutating + [client-owned fields](0111.md#single-owner-fields) of any resource other + than the target of the request. The dependent mutation **must** be performed + through the dependent resource's own endpoint; if the operation is + fundamentally multi-resource by design, it **must** be modeled as a custom + method per the rule above. + - Side effects limited to read-only or + [effective values](0111.md#effective-values) of another resource **may** + occur in standard methods. - Standard methods **must** guarantee [atomicity](https://en.wikipedia.org/wiki/Atomicity_%28database_systems%29) - In cases where atomicity cannot be guaranteed, consider in the following @@ -36,6 +45,19 @@ Selecting a custom method may be valuable for: - If atomic modifications are required when adding or removing from repeated fields +### Response bodies + +- Every endpoint **must** support a versioned JSON content type (e.g. + `application/vnd.atlas.YYYY-MM-DD+json`), per [IPA-900](../sdks/0900.md). + Additional content types (e.g. `+csv`) **may** be offered alongside JSON. +- When a response body is returned as a JSON content type, it **must** be a JSON + object with a fixed set of named properties at the root. + - Top-level arrays, primitives, or objects with dynamic (unknown) keys at the + root are prohibited because they cannot be consistently typed by + schema-based clients and tooling. + - Collections **must** be wrapped in an envelope object per [IPA-110](0110.md) + (e.g. `{"results": [...], "links": [...], "totalCount": 42}`). + ### Naming - The method name is the