Merge branch 'main' into CLOUDP-366822

Author: matt-condon

ipa/general/0106.md

@@ -19,6 +19,9 @@ Adopt
 
 - APIs **should** provide a create method for resources unless it is not
   valuable for users to do so
+  - [Read-only resources](0101.md#read-only-resources) **must not** have a
+    Create method
+  - [Singleton resources](0113.md) **must not** have a Create method
   - The purpose of the create method is to create a new resource in a collection
 - The HTTP verb **must** be
   [`POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST)

ipa/general/0107.md

@@ -19,6 +19,10 @@ Adopt
 
 - APIs **should** provide an update method for resources unless it is not
   valuable for users to do so
+  - [Read-only resources](0101.md#read-only-resources) **must not** have an
+    Update method
+  - [Read-only singleton resources](0113.md#read-only-singleton-resources)
+    **must not** have an Update method
   - The purpose of the Update method is to make changes to the resources without
     causing side effects
 - The HTTP verb **should** be

ipa/general/0108.md

@@ -19,6 +19,9 @@ Adopt
 
 - APIs **should** provide a Delete method for resources unless it is not
   valuable for users to do so
+  - [Read-only resources](0101.md#read-only-resources) **must not** have a
+    Delete method
+  - [Singleton resources](0113.md) **must not** have a Delete method
 - The HTTP verb **must** be
   [`DELETE`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE)
 - The response **should** be empty

ipa/general/0109.md

@@ -64,8 +64,8 @@ POST /groups/${groupId}/clusters/${clusterName}:removeNode
 
 ### Declarative-friendly resources
 
-- Declarative-friendly resources **must not** use custom methods. To learn more,
-  see [IPA-127](0127.md).
+- Declarative-friendly resources **should not** use custom methods. To learn
+  more, see [IPA-127](0127.md).
   - Custom methods require manual curation, implementation, and review for API
     tooling, which increases feature latency.
   - Declarative-friendly tools are unable to automatically determine what to do

ipa/general/0111.md

@@ -12,7 +12,7 @@ may modify and return values are complex, not public, and not repeatable.
 
 :::warning[State]
 
-Experimental
+Adopt
 
 :::
 

ipa/general/0113.md

@@ -53,3 +53,22 @@ modified by API consumers.
 - Unsupported operations on read-only singleton resources **should** return
   `405 Not Allowed`
 - Unsupported operations **must not** be documented
+
+### Resetting Singleton Resources
+
+Singleton resources can be restored to their default state without deleting the
+parent resource. For such cases, a `:reset` [custom method](0109.md) **must** be
+used.
+
+- The `:reset` custom method name **must** be reserved exclusively for restoring
+  singleton resources to their default state
+- The `:reset` custom method **must** use the `POST` HTTP method
+- The `:reset` custom method **must** be idempotent
+  - Calling reset multiple times **must** produce the same result as calling it
+    once
+- The `:reset` custom method **must** return a
+  [200 OK](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200)
+  response with the reset resource in the response body
+- The `:reset` custom method **must not** have a request body
+- Read-only singleton resources **must not** define a `:reset` custom method
+  - Read-only singleton resources cannot be modified, so reset is not applicable

ipa/general/0114.md

@@ -24,14 +24,8 @@ Adopt
   validations and exposing the appropriate error user error (4XX)
 - Errors **must** use the canonical error codes allowed for the `errorCode`
   field
-- APIs **should** make the best effort to validate as much as possible of the
-  request and include all validation errors in the field `badRequestDetail`
-  - `badRequestDetail` **must** include an array of fields and each field
-    **must** include:
-    - the error description as `description`
-    - field with errors as `field`
-- APIs **should** make the best effort to help customers with possible next
-  steps in case of an error by adding the help field
+- APIs **may** make the best effort to help customers with possible next steps
+  in case of an error by adding a `help` field
   - `help` **must** include a short description as description
   - `help` **must** include a link to the documentation url
 - [Methods](0103.md) **must** document any possible error and their associated
@@ -78,6 +72,30 @@ are treated as `404 Not Found` rather than `400 Bad Request`.
     limit window
 
 :::
+### Validation Errors
+
+Validation errors occur when the client sends a request that does not meet the
+API's requirements. Proper validation is critical for maintaining data integrity
+and providing clear feedback to clients.
+
+Validation errors typically occur when:
+
+- Required fields are missing
+- Data types don't match expected formats
+- Values fall outside acceptable ranges
+- Business rules are violated
+
+- APIs **must** return a `400 Bad Request` status code when validation fails
+- APIs **must not** accept invalid requests and silently modify field values to
+  make them valid
+  - This violates the principle that client-owned fields must not be modified by
+    the server (see [IPA-111](0111.md#single-owner-fields))
+- APIs **should** make the best effort to validate as much as possible of the
+  request and include all validation errors in the field `badRequestDetail`
+  - `badRequestDetail` **must** include an array of fields and each field
+    **must** include:
+    - the error description as `description`
+    - field with errors as `field`
 
 ### API Error Format
 

ipa/general/0116.md

@@ -65,6 +65,7 @@ Changes considered non-breaking include:
 - Response headers **may** be added to existing versions
 - Changes to a resources authorization **may** be added to existing versions
 - New options **may** be added to existing enums
+- Input and output fields **may** be marked as deprecated in existing versions
 
 ### Semantic Breaking Changes
 

ipa/general/0117.md

@@ -152,6 +152,9 @@ Operation summaries are titles describing an API operation.
 - API Producers **must** use only one main action verb e.g. "Create," "Update,"
   "Delete," "Add," "Remove"
 - API Producers **must** use "Update" instead of "Modify" or "Change"
+- API Producers **must** use "Reset" when the operation is restoring a resource
+  to its default state
+  - E.g. "Reset Project Settings for One MongoDB Cloud User"
 - API Producers **must** use "in" for actions operating within the parent
   (retrieving, updating, creating) and "from" for removing/disassociating
   - "Remove One MongoDB Cloud User from One Project" instead of "Remove One

ipa/general/0127.md

@@ -7,7 +7,7 @@ slug: /127
 
 :::warning[State]
 
-Experimental
+Adopt
 
 :::
 
@@ -17,51 +17,33 @@ such as **Infrastructure as Code (IaC) tools**, which many customers heavily
 depend on for their DevOps workflows.\
 An interface is considered "declarative-friendly" when resources can be managed
 by specifying their **desired final state**, rather than outlining a series of
-steps or actions. In this approach, you define **what** the resource should look
-like, while the API takes care of the **how**.
+steps or actions. In this approach, a user defines **what** the resource should
+look like via an IaC tool, while the tool and underlying API take care of the
+**how**.
 
 With the wide range of popular IaC tools and the constant demand to integrate
 diverse resource types across multiple platforms, **uniformity** is critical to
 fully automating these integrations.\
-The following guidance is to enable interfaces to be **declarative-friendly**
-and support **automation**.
+
+:::warning[Important]
+
+In addition to the existing guidelines, **declarative-friendly** interfaces
+require extra, stricter guidance to support IaC tooling automation.
+
+:::
 
 ## Guidance
 
 - A resource **must** be strongly consistent with the **Resource-Oriented
   Design** ([IPA-101](0101.md))
-  - An interface **must** expose the full resource lifecycle using standard HTTP
-    verbs. The `GET` operation is critical for IaC tools to read the current
-    state and compare it against the desired state.
-- A resource **must** have `CREATE`, `DELETE`, `GET`, `LIST` and `UPDATE`
-  methods, except for [read-only resources](#read-only-resources) which **must**
-  have only `GET` and `LIST` methods.
-  - Response schemas of `CREATE`, `GET` and `UPDATE` **must** be the same
-  - Fields defined in `CREATE` and `UPDATE` request schemas **should be** the
-    same and **should** be present in response schema
-  - For full guidance, see [IPA-103](0103.md), [IPA-104](0104.md),
-    [IPA-105](0105.md), [IPA-106](0106.md), [IPA-107](0107.md),
-    [IPA-108](0108.md)
-- A resource **must not** have custom methods ([IPA-109](0109.md)) as they make
-  some automations impossible. Any deviation from this guidance requires a
+- A resource **must** have `CREATE`, `DELETE`, `GET`, `LIST` methods, except for
+  [singleton resources](0113.md) and
+  [read-only resources](0101.md#read-only-resources) which **must** have `GET`
+  and `LIST` methods.
+- A resource **should not** have custom methods ([IPA-109](0109.md)). Any
+  complementary functionality of a resource exposed through custom methods will
+  not be supported through automation. Deviation from this guidance requires a
   strong justification and review by the governing API body.
-- A resource field **must** have a single owner ([IPA-111](0111.md))
-  - Effective fields **must** be used when a client-owned field can also be
-    controlled by the server
-- A resource field name **must** be consistent in between the request, response
-  body and path parameters ([IPA-112](0112.md))
-- A resource **must** have a standardized error format so that consumers can
-  fully rely on understandable API responses ([IPA-114](0114.md))
-- A resource field **should** have a single type ([IPA-125](0125.md))
-
-### Read-Only Resources
-
-[Read-only resources](0101.md#read-only-resources) are declarative-friendly when
-they provide observable state that IaC tools need to reference or depend upon.
-
-For full guidance on read-only resources, see
-[IPA-101](0101.md#read-only-resources). For read-only singleton resources, see
-[IPA-113](0113.md#read-only-singleton-resources).
 
 ### Motivation and Strategic Goals
 
@@ -76,3 +58,15 @@ are predictably declarative, we can build automations that create and maintain
 tools such as our Terraform and CloudFormation providers. This will dramatically
 accelerate the availability of IaC support for our products and reduce manual,
 error-prone development.
+
+### Further Reading
+
+- [IPA-101: Resource-Oriented Design](0101.md)
+- [IPA-104: Get](0104.md)
+- [IPA-105: List](0105.md)
+- [IPA-106: Create](0106.md)
+- [IPA-108: Delete](0108.md)
+- [IPA-109: Custom Methods](0109.md)
+- [IPA-111: Server-Modified Values and Defaults](0111.md)
+- [IPA-114: Errors](0114.md)
+- [IPA-125: Single Type in Request and Response](0125.md)