diff --git a/ipa/general/0101.md b/ipa/general/0101.md index 86582b2..b96daa0 100644 --- a/ipa/general/0101.md +++ b/ipa/general/0101.md @@ -88,9 +88,20 @@ standard methods: - [Custom methods](0109.md) help define functionality that does not cleanly map to any of the standard methods -### Readonly Resources - -- Unsupported operations on readonly resources **should** return +### Read-Only Resources + +Read-only resources are resources that cannot be modified by API consumers. + +- Read-only resources **must** have [Get](0104.md) and [List](0105.md) methods +- Read-only resources **must not** have [Create](0106.md), [Update](0107.md), or + [Delete](0108.md) methods +- Read-only resources **may** have [custom methods](0109.md) as appropriate +- All response schema properties for read-only resources **must** be marked as + read-only + - In OpenAPI, this means all properties **must** have `readOnly: true` + - All fields in read-only resources are server-owned. For guidance on + server-owned fields, see [IPA-111](0111.md#single-owner-fields) +- Unsupported operations on read-only resources **should** return `405 Not Allowed` - Unsupported operations **must not** be documented - Some declarative-friendly clients require all standard methods to be diff --git a/ipa/general/0111.md b/ipa/general/0111.md index af48c21..2ceba4f 100644 --- a/ipa/general/0111.md +++ b/ipa/general/0111.md @@ -21,34 +21,56 @@ Experimental ### Single Owner Fields Fields **must** have a single owner, whether that is the client or the server. -Server-owned fields must be documented as such. All other types of fields -**must** be considered to be owned by the client. The server **must** respect -the value (or lack thereof) of all client-owned fields and not modify them. + +- **Server-owned fields** are fields that are controlled and modified by the + service + - Server-owned fields **must** be documented as read-only + - In OpenAPI, server-owned fields **must** have `readOnly: true` + - Server-owned fields **must not** be accepted in request bodies for + [Create](0106.md) or [Update](0107.md) operations +- **Client-owned fields** are fields that are controlled by the client + - All fields that are not explicitly documented as server-owned **must** be + considered client-owned + - The server **must** respect the value (or lack thereof) of all client-owned + fields and not modify them + - The server **must** always return the same value the client sent (or absence + of value) for client-owned fields + +:::note + +For resources where all fields are server-owned, see +[read-only resources](0101.md#read-only-resources) and +[read-only singleton resources](0113.md#read-only-singleton-resources). + +::: ### Effective Values There are instances where a service will allocate, generate, or calculate a -value if the client chooses not to specify one. - -**For example:** a client creates a cluster without specifying a version. Such a -scenario is opting for the default mongodb version. +value that may differ from what the client specified. An attribute with an effective value **must** be expressed as two fields in the API: -- A mutable field that **may** be optionally set by the user and **must not** be - modified by the service -- A read-only field that records the effective value decided on by the service - - Effective values **must** be named by prefixing effective to the mutable +- A **client-owned** mutable field that **may** be optionally set by the user + and **must not** be modified by the service +- A **server-owned** read-only field that records the effective value decided on + by the service + - Effective values **must** be named by prefixing `effective` to the mutable field's name + - In OpenAPI, the effective value field **must** have `readOnly: true` Example +A cluster's instance size may have a different computed value from the server if +auto-scaling is enabled. The client specifies their desired instance size, but +the server may scale it up or down based on load. + ```json -// For managing autoscaling of a cluster +// For managing a cluster with auto-scaling enabled { - "clusterTier": "M10", - "effectiveClusterTier": "M30" + "instanceSize": "M10", + "effectiveInstanceSize": "M30" } ``` diff --git a/ipa/general/0113.md b/ipa/general/0113.md index 9cca4da..9fd2c4a 100644 --- a/ipa/general/0113.md +++ b/ipa/general/0113.md @@ -22,8 +22,9 @@ Adopt [Delete](0108.md) standard methods - The singleton is implicitly created or deleted when its parent is created or deleted -- Singleton resources **should** define the [Get](0104.md) and [Update](0107.md) - methods +- Singleton resources **must** define the [Get](0104.md) method +- Singleton resources **should** define the [Update](0107.md) method, unless the + resource is [read-only](0113.md#read-only-singleton-resources) - Singleton resources **may** define [custom methods](0109.md) as appropriate Example @@ -33,3 +34,22 @@ GET /groups/${groupId}/settings ### PATCH /groups/${groupId}/settings ``` + +### Read-Only Singleton Resources + +Read-only singleton resources are [singleton resources](0113.md) that cannot be +modified by API consumers. + +- Read-only singleton resources **must** have only the [Get](0104.md) method +- Read-only singleton resources **must not** have [Create](0106.md), + [Update](0107.md), or [Delete](0108.md) methods +- Read-only singleton resources **may** have [custom methods](0109.md) as + appropriate, provided they do not modify the resource +- All response schema properties for read-only singleton resources **must** be + marked as read-only + - In OpenAPI, this means all properties **must** have `readOnly: true` + - All fields in read-only singleton resources are server-owned. For guidance + on server-owned fields, see [IPA-111](0111.md#single-owner-fields) +- Unsupported operations on read-only singleton resources **should** return + `405 Not Allowed` +- Unsupported operations **must not** be documented diff --git a/ipa/general/0127.md b/ipa/general/0127.md index 0c9b790..63f9811 100644 --- a/ipa/general/0127.md +++ b/ipa/general/0127.md @@ -34,7 +34,8 @@ and support **automation**. 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. + 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 @@ -53,6 +54,15 @@ and support **automation**. 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 Our engineering teams and customers rely on IaC tools to manage infrastructure